@huynle/hub 0.7.4 → 0.8.0

package/packages/cli/src/team-intake-mcp.ts

@@ -0,0 +1,158 @@
+// MCP tools for team intake (HWA-36): team_submit gives work to a team (its entry role, e.g. a project manager,
+// receives it with the team's context and owns it as a workspace assignment), team_intake reads one item or the
+// list, team_intake_update reports progress or completion explicitly (nothing is inferred from idleness). `team` is
+// the team's ID (team_…); name lookup arrives with the teams API (HWA-37). An app token needs scope teams:submit;
+// sessions submit under team policy and, in the team's entry role, report status.
+import { sanitizeText } from "../../sdk/src/envelope.ts"
+import { reportIntakeStatus, TEAM_INTAKE_STATUS_INPUTS, type TeamIntake, type TeamIntakeApi, type TeamIntakePriority, type TeamIntakeStatus, type TeamIntakeStatusInput } from "../../sdk/src/team-intake.ts"
+
+type Args = Record<string, unknown>
+
+/** The shape of an MCP tool (as packages/cli/src/mcp.ts registers them). */
+export interface TeamIntakeTool {
+  readonly name: string
+  readonly description: string
+  readonly properties: Record<string, unknown>
+  readonly required?: readonly string[]
+  readonly readOnly: boolean
+  readonly organizes?: boolean
+  readonly idempotent?: boolean
+  run(hub: { readonly teams: TeamIntakeApi }, args: Args, signal: AbortSignal): Promise<string>
+}
+
+const STRING = { type: "string" } as const
+const TEAM = { type: "string", description: "The team's ID (team_…)." } as const
+const INTAKE = { type: "string", description: "The intake item's ID (itk_…)." } as const
+const PRIORITIES: readonly TeamIntakePriority[] = ["low", "normal", "high", "urgent"]
+const STATUSES: readonly TeamIntakeStatus[] = ["queued", "routed", "done", "cancelled", "failed"]
+const UPDATES: readonly TeamIntakeStatusInput[] = TEAM_INTAKE_STATUS_INPUTS
+
+const need = (args: Args, key: string): string => {
+  const value = args[key]
+  if (typeof value !== "string" || !value.trim()) throw new Error(`"${key}" is required (a non-empty string)`)
+  return value
+}
+const optional = (args: Args, key: string): string | undefined => {
+  const value = args[key]
+  if (value === undefined || value === null) return undefined
+  if (typeof value !== "string") throw new Error(`"${key}" must be a string`)
+  return value.trim() ? value : undefined
+}
+const strings = (args: Args, key: string): string[] | undefined => {
+  const value = args[key]
+  if (value === undefined || value === null) return undefined
+  if (!Array.isArray(value) || !value.every((v) => typeof v === "string")) throw new Error(`"${key}" must be a list of strings`)
+  return value
+}
+const oneOf = <T extends string>(args: Args, key: string, allowed: readonly T[]): T | undefined => {
+  const value = optional(args, key)
+  if (value !== undefined && !allowed.includes(value as T)) throw new Error(`"${key}" must be one of ${allowed.join(", ")}`)
+  return value as T | undefined
+}
+
+/** `due` as an ISO date/time or epoch milliseconds. */
+function dueOf(args: Args): number | undefined {
+  const value = args.due
+  if (value === undefined || value === null || value === "") return undefined
+  const ms = typeof value === "number" ? value : typeof value === "string" ? Date.parse(value) : Number.NaN
+  if (!Number.isSafeInteger(ms) || ms <= 0) throw new Error(`"due" must be an ISO date/time or epoch milliseconds`)
+  return ms
+}
+
+const line = (i: TeamIntake) =>
+  `${i.id}  ${i.status}${i.progress ? `/${i.progress}` : ""}  ${i.priority}  r${i.revision}  ${sanitizeText(i.title).replace(/\s+/g, " ")}`
+
+function intakeText(i: TeamIntake): string {
+  const from = i.source.kind === "user" ? "the user" : i.source.kind === "app" ? `app ${i.source.tokenID}` : `session ${i.source.sessionID}`
+  return [
+    `${i.id} (team ${i.teamID}) revision ${i.revision}`,
+    `title: ${sanitizeText(i.title).replace(/\s+/g, " ")}`,
+    `status: ${i.status}${i.progress ? ` (${i.progress})` : ""}  priority: ${i.priority}  from: ${from}`,
+    ...(i.assignmentID ? [`assignment: ${i.assignmentID} in workspace ${i.workspaceID ?? "?"}${i.sessionID ? `, delivered to ${i.sessionID}` : ""}`] : []),
+    ...(i.due !== undefined ? [`due: ${new Date(i.due).toISOString()}`] : []),
+    ...(i.labels?.length ? [`labels: ${i.labels.join(", ")}`] : []),
+    ...(i.criteria?.length ? ["done means:", ...i.criteria.map((c) => `- ${sanitizeText(c)}`)] : []),
+    ...(i.ref ? [`ref: ${sanitizeText(i.ref)}`] : []),
+    ...(i.reason ? [`reason: ${sanitizeText(i.reason)}`] : []),
+    ...(i.lastError ? [`last routing error: ${i.lastError} (retried)`] : []),
+  ].join("\n")
+}
+
+export const teamIntakeTools: readonly TeamIntakeTool[] = [
+  {
+    name: "team_submit",
+    description:
+      "Give work to a team: its entry role (e.g. the project manager) receives the task with the team's context and owns it as an assignment in the team's workspace; while the role is vacant it waits queued. Pass `key` to make retries idempotent. App tokens need scope teams:submit; sessions submit under the team's communication policy.",
+    properties: {
+      team: TEAM,
+      title: { ...STRING, description: "One line, at most 120 characters." },
+      brief: { ...STRING, description: "The task's details (delivered in the message only; at most 16000 characters)." },
+      priority: { type: "string", enum: PRIORITIES, description: "Default normal." },
+      labels: { type: "array", items: STRING, description: "Slugs (lowercase letters, digits, dashes)." },
+      due: { ...STRING, description: "When it is due: an ISO date/time." },
+      criteria: { type: "array", items: STRING, description: "What done means (at most 8 lines)." },
+      ref: { ...STRING, description: "An external reference, e.g. a Brain task ID." },
+      key: { ...STRING, description: "Idempotency-Key: the same key and body return the original submission." },
+    },
+    required: ["team", "title"],
+    readOnly: false,
+    idempotent: false,
+    run: async (hub, args, signal) => {
+      const priority = oneOf(args, "priority", PRIORITIES)
+      const labels = strings(args, "labels")
+      const criteria = strings(args, "criteria")
+      const due = dueOf(args)
+      const brief = optional(args, "brief")
+      const ref = optional(args, "ref")
+      const key = optional(args, "key")
+      const { intake, created } = await hub.teams.submit(
+        need(args, "team"),
+        { title: need(args, "title"), ...(brief ? { brief } : {}), ...(priority ? { priority } : {}), ...(labels ? { labels } : {}), ...(due !== undefined ? { due } : {}), ...(criteria ? { criteria } : {}), ...(ref ? { ref } : {}) },
+        { signal, ...(key ? { idempotencyKey: key } : {}) },
+      )
+      return `${created ? "Submitted" : "Already submitted (same key)"}: ${intake.id} is ${intake.status}${intake.status === "queued" ? " (waiting for the entry role)" : ""}\n${intakeText(intake)}`
+    },
+  },
+  {
+    name: "team_intake",
+    description: "One intake item of a team (with `intake`), or the team's intake list (optionally by status). Apps with teams:submit see their own submissions.",
+    properties: { team: TEAM, intake: INTAKE, status: { type: "string", enum: STATUSES, description: "Only items in this status (list)." }, cursor: { ...STRING, description: "The cursor of the previous page (list)." } },
+    required: ["team"],
+    readOnly: true,
+    run: async (hub, args, signal) => {
+      const team = need(args, "team")
+      const id = optional(args, "intake")
+      if (id) return intakeText((await hub.teams.intake(team, id, { signal })).intake)
+      const status = oneOf(args, "status", STATUSES)
+      const cursor = optional(args, "cursor")
+      const page = await hub.teams.intakes(team, { signal, ...(status ? { status } : {}), ...(cursor ? { cursor } : {}) })
+      if (page.items.length === 0) return "No intake."
+      return [...page.items.map(line), ...(page.cursor ? [`more: cursor ${page.cursor}`] : [])].join("\n")
+    },
+  },
+  {
+    name: "team_intake_update",
+    description:
+      "Report an intake item's progress or completion explicitly: in_progress, blocked, open, done, failed (the team's entry role or the user), or cancelled (also the submitter). Close it with done when finished, or failed with a one-line reason. expectedRevision is optional: without it the current revision is read first; a change in between is a conflict.",
+    properties: {
+      team: TEAM,
+      intake: INTAKE,
+      status: { type: "string", enum: UPDATES },
+      expectedRevision: { type: "integer", description: "The revision you read (optional: the current one is read when omitted)." },
+      reason: { ...STRING, description: "Why it failed or was cancelled (one line)." },
+    },
+    required: ["team", "intake", "status"],
+    readOnly: false,
+    idempotent: true,
+    run: async (hub, args, signal) => {
+      const status = oneOf(args, "status", UPDATES)
+      if (!status) throw new Error(`"status" is required: one of ${UPDATES.join(", ")}`)
+      const expectedRevision = args.expectedRevision
+      if (expectedRevision !== undefined && expectedRevision !== null && (typeof expectedRevision !== "number" || !Number.isSafeInteger(expectedRevision) || expectedRevision < 0))
+        throw new Error(`"expectedRevision" must be the revision you read (or left out)`)
+      const reason = optional(args, "reason")
+      const { intake, assignment } = await reportIntakeStatus(hub.teams, need(args, "team"), need(args, "intake"), { status, ...(typeof expectedRevision === "number" ? { expectedRevision } : {}), ...(reason ? { reason } : {}) }, { signal })
+      return `${intake.id} is ${intake.status}${intake.progress ? ` (${intake.progress})` : ""}, revision ${intake.revision}${assignment ? `; assignment ${assignment.id} ${assignment.status}` : ""}`
+    },
+  },
+]

package/packages/cli/src/teams-mcp.ts

@@ -0,0 +1,403 @@
+// MCP tools for persistent teams (HWA-37): assemble a team (roles, one entry role, open or restricted communication
+// with one-way/two-way paths), edit it as a draft and publish it, staff its roles with sessions, and operate it
+// (status, pause/resume, archive/restore). Work is given to a team with team_submit (team-intake-mcp.ts, HWA-36).
+// `team` is the team's ID (team_…) or its name.
+//
+// Annotations for gateway review (packages/cli/src/mcp.ts maps them): reads are readOnlyHint; draft edits, create and
+// pause/resume only reorganize (destructiveHint false: nothing applies until publish, and they are reversible);
+// publish (changes the enforced communication policy), discard (drops unpublished edits), archive/restore (turn
+// policy enforcement off/on) and staffing (seats confer the team's policy on a session; launches start sessions) keep
+// the default destructiveHint. Changes of existing records send expectedRevision, so repeating one is idempotent.
+// Decision answers and grant administration stay console-only: there is no tool for them here.
+import { sanitizeText } from "../../sdk/src/envelope.ts"
+import type { LaunchSpec } from "../../sdk/src/types.ts"
+import type { Team, TeamDraft, TeamEdge, TeamPatch, TeamRole, TeamRoster, Teams, TeamSpec } from "../../sdk/src/teams.ts"
+
+type Args = Record<string, unknown>
+
+/** The shape of an MCP tool (as packages/cli/src/mcp.ts registers them). */
+export interface TeamTool {
+  readonly name: string
+  readonly description: string
+  readonly properties: Record<string, unknown>
+  readonly required?: readonly string[]
+  readonly readOnly: boolean
+  readonly organizes?: boolean
+  readonly idempotent?: boolean
+  run(hub: { readonly teams: Teams }, args: Args, signal: AbortSignal): Promise<string>
+}
+
+const STRING = { type: "string" } as const
+const STRINGS = { type: "array", items: STRING } as const
+const TEAM = { type: "string", description: "The team: its ID (team_…) or its name." } as const
+const REVISION = { type: "integer", minimum: 0, description: "The team's revision you read (team_show); a stale one answers conflict with the current revision." } as const
+const IDEMPOTENCY = { type: "string", description: "Idempotency-Key: the same key and arguments within 24 h answer the first result again." } as const
+const KINDS = { type: "array", items: { type: "string", enum: ["msg", "ask"] }, description: "What the path permits: msg and/or ask (replies to a permitted ask never need a path)." } as const
+const DIRECTION = { type: "string", enum: ["one-way", "two-way"], description: "two-way: `to` may also contact `from` with the same kinds." } as const
+const ROLE_FIELDS = {
+  label: { ...STRING, description: "A display label (confers no authority)." },
+  description: STRING,
+  externalContact: { type: "boolean", description: "Holders may contact sessions outside all their teams (default false)." },
+  responsibilities: { ...STRINGS, description: "Short lines (at most 16)." },
+  profile: { type: "object", properties: { profileID: STRING, version: { type: "integer", minimum: 1 } }, required: ["profileID"], description: "The agent profile members should run (reported, never pinned by staffing)." },
+  prefs: { type: "object", properties: { harness: STRING, model: STRING, machineID: STRING }, description: "Placement preferences for launched members (advisory)." },
+  minMembers: { type: "integer", minimum: 0, maximum: 16 },
+  maxMembers: { type: "integer", minimum: 1, maximum: 16 },
+} as const
+const ROLE = { type: "object", properties: { name: { ...STRING, description: "A slug: lowercase letters, digits, dashes." }, ...ROLE_FIELDS }, required: ["name"] } as const
+const EDGE = { type: "object", properties: { from: STRING, to: STRING, kinds: KINDS, direction: DIRECTION }, required: ["from", "to", "kinds", "direction"] } as const
+const SPEC_FIELDS = {
+  title: { ...STRING, description: "1–120 characters." },
+  description: STRING,
+  mode: { type: "string", enum: ["open", "restricted"], description: "open: every member may msg/ask every other member. restricted: only the drawn paths (edges)." },
+  roles: { type: "array", items: ROLE, description: "1–32 roles." },
+  entryRole: { ...STRING, description: "The role that receives submitted work (e.g. pm) and supervises members." },
+  edges: { type: "array", items: EDGE, description: "Communication paths between roles (restricted mode)." },
+  tags: { ...STRINGS, description: "Slugs." },
+  metadata: { type: "object", additionalProperties: STRING, description: "String key/value pairs (keys are slugs)." },
+  projects: { ...STRINGS, description: "Project names the team works on." },
+} as const
+const SCOPES = "App tokens need scope teams:read (reads) or teams:manage (changes); seats, status and staffing also need sessions:read. Session tokens read only teams they are seated in and never change definitions. Team roles confer no authority."
+
+class ArgError extends Error {}
+
+const need = (args: Args, key: string): string => {
+  const value = args[key]
+  if (typeof value !== "string" || !value.trim()) throw new ArgError(`"${key}" is required (a non-empty string)`)
+  return value
+}
+const optional = (args: Args, key: string): string | undefined => {
+  const value = args[key]
+  if (value === undefined || value === null) return undefined
+  if (typeof value !== "string") throw new ArgError(`"${key}" must be a string`)
+  return value.trim() ? value : undefined
+}
+const strings = (args: Args, key: string): string[] | undefined => {
+  const value = args[key]
+  if (value === undefined || value === null) return undefined
+  if (!Array.isArray(value) || !value.every((v) => typeof v === "string")) throw new ArgError(`"${key}" must be a list of strings`)
+  return value
+}
+const revision = (args: Args): number => {
+  const value = args.expectedRevision
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw new ArgError(`"expectedRevision" is required: the team's revision you read (team_show)`)
+  return value
+}
+const int = (args: Args, key: string, min: number, max: number): number | undefined => {
+  const value = args[key]
+  if (value === undefined || value === null) return undefined
+  if (typeof value !== "number" || !Number.isInteger(value) || value < min || value > max) throw new ArgError(`"${key}" must be a whole number from ${min} to ${max}`)
+  return value
+}
+const record = (args: Args, key: string): Record<string, string> | undefined => {
+  const value = args[key]
+  if (value === undefined || value === null) return undefined
+  if (typeof value !== "object" || Array.isArray(value) || !Object.values(value).every((v) => typeof v === "string")) throw new ArgError(`"${key}" must be an object of strings`)
+  return value as Record<string, string>
+}
+const launchOf = (args: Args): LaunchSpec | undefined => {
+  const value = args.launch
+  if (value === undefined || value === null) return undefined
+  if (typeof value !== "object" || Array.isArray(value)) throw new ArgError(`"launch" must be a launch spec object (as the launch tool takes)`)
+  return value as LaunchSpec
+}
+/** The given fields of `keys` (undefined ones dropped). */
+const picked = (args: Args, keys: readonly string[]): Record<string, unknown> => Object.fromEntries(keys.filter((k) => args[k] !== undefined).map((k) => [k, args[k]]))
+
+const one = (text: string) => sanitizeText(text).replace(/\s+/g, " ")
+const when = (ms: number) => new Date(ms).toISOString()
+
+/** `team_…  name  state[ paused]  vN rN[  draft pending]  title` */
+export const teamLine = (t: Team): string =>
+  `${t.id}  ${t.name}  ${t.state}${t.paused ? " paused" : ""}  v${t.version} r${t.revision}${t.draft ? "  (draft pending)" : ""}  ${one(t.title)}`
+
+const edgeText = (e: TeamEdge) => `${e.from} ${e.direction === "two-way" ? "⇄" : "→"} ${e.to} (${e.kinds.join(", ")})`
+
+function specLines(spec: TeamSpec): string[] {
+  const role = (r: TeamRole) =>
+    `  ${r.name}${r.name === spec.entryRole ? " (entry)" : ""}${r.label ? `  "${one(r.label)}"` : ""}${r.externalContact ? "  external contact" : ""}${r.minMembers !== undefined || r.maxMembers !== undefined ? `  members ${r.minMembers ?? 0}–${r.maxMembers ?? 16}` : ""}${r.profile ? `  profile ${r.profile.profileID}${r.profile.version ? `@${r.profile.version}` : ""}` : ""}`
+  return [
+    `mode: ${spec.mode}${spec.mode === "open" ? " (every member may msg/ask every other)" : " (only the paths below)"}`,
+    `entry role: ${spec.entryRole}`,
+    "roles:",
+    ...spec.roles.map(role),
+    ...(spec.edges.length ? ["paths:", ...spec.edges.map((e) => `  ${edgeText(e)}`)] : ["paths: none"]),
+    ...(spec.tags?.length ? [`tags: ${spec.tags.join(", ")}`] : []),
+    ...(spec.projects?.length ? [`projects: ${spec.projects.map(one).join(", ")}`] : []),
+    ...(spec.metadata && Object.keys(spec.metadata).length ? [`metadata: ${Object.entries(spec.metadata).map(([k, v]) => `${k}=${one(v)}`).join(", ")}`] : []),
+    ...(spec.description ? [`description: ${one(spec.description)}`] : []),
+  ]
+}
+
+const draftText = (prefix: string, team: Team, draft: TeamDraft | undefined) =>
+  [`${prefix}: ${teamLine(team)}`, ...(draft ? [`draft (on v${draft.baseVersion}, saved ${when(draft.savedAt)}; publish with team_publish):`, ...specLines(draft.spec)] : [])].join("\n")
+
+function rosterLines(roster: TeamRoster): string[] {
+  const lines = [`roster (v${roster.version}${roster.paused ? ", paused" : ""})${roster.workspace ? `  workspace ${roster.workspace.id} ${roster.workspace.state}` : ""}:`]
+  for (const r of roster.roles) {
+    const flags = [r.vacant ? "vacant" : "", r.understaffed ? `understaffed (min ${r.minMembers})` : "", r.launching ? `${r.launching} launching` : ""].filter(Boolean)
+    lines.push(`  ${r.role}${r.entry ? " (entry)" : ""}  ${r.seats.length}/${r.maxMembers}  ${r.online} online${flags.length ? `  ${flags.join(", ")}` : ""}`)
+    for (const s of r.seats)
+      lines.push(`    ${s.staffing.id}  ${s.staffing.sessionID}  ${s.presence}  gen ${s.staffing.generation} r${s.staffing.revision}${s.profile ? `  profile ${s.profile.status}${s.profile.matches ? "" : " (mismatch)"}` : ""}`)
+  }
+  const failed = roster.requests.filter((q) => q.state !== "staffed").slice(-5)
+  for (const q of failed) lines.push(`  launch ${q.id}  ${q.role}  ${q.state}${q.reason ? `: ${one(q.reason)}` : ""}`)
+  return lines
+}
+
+const statusTool = (verb: "pause" | "resume" | "archive" | "restore", description: string, organizes: boolean): TeamTool => ({
+  name: `team_${verb}`,
+  description: `${description} ${SCOPES}`,
+  properties: { team: TEAM, expectedRevision: REVISION },
+  required: ["team", "expectedRevision"],
+  readOnly: false,
+  ...(organizes ? { organizes: true } : {}),
+  idempotent: true,
+  run: async (hub, args, signal) => {
+    const expectedRevision = revision(args)
+    const { team } = await hub.teams[verb](need(args, "team"), expectedRevision, { signal })
+    return `${team.revision === expectedRevision ? "unchanged" : { pause: "paused", resume: "resumed", archive: "archived", restore: "restored" }[verb]}: ${teamLine(team)}`
+  },
+})
+
+const draftTool = (name: string, description: string, properties: Record<string, unknown>, required: readonly string[], edit: (teams: Teams, team: string, args: Args, expectedRevision: number, signal: AbortSignal) => Promise<{ team: Team; draft: TeamDraft }>): TeamTool => ({
+  name,
+  description: `${description} Changes the draft only: nothing applies until team_publish. ${SCOPES}`,
+  properties: { team: TEAM, ...properties, expectedRevision: REVISION },
+  required: ["team", ...required, "expectedRevision"],
+  readOnly: false,
+  organizes: true,
+  idempotent: true,
+  run: async (hub, args, signal) => {
+    const expectedRevision = revision(args)
+    const { team, draft } = await edit(hub.teams, need(args, "team"), args, expectedRevision, signal)
+    return draftText("draft saved", team, draft)
+  },
+})
+
+export const teamTools: readonly TeamTool[] = [
+  // ---------- reads ----------
+  {
+    name: "teams",
+    description: `List the user's teams (id, name, state, version, revision, title), filtered by tags (all of them), project, metadata pairs, state and pause; paged. ${SCOPES}`,
+    properties: {
+      state: { type: "string", enum: ["active", "archived", "all"] },
+      tags: STRINGS,
+      project: STRING,
+      metadata: { type: "object", additionalProperties: STRING },
+      paused: { type: "boolean" },
+      limit: { type: "integer", minimum: 1, maximum: 200 },
+      cursor: STRING,
+    },
+    readOnly: true,
+    run: async (hub, args, signal) => {
+      const state = optional(args, "state")
+      if (state !== undefined && !["active", "archived", "all"].includes(state)) throw new ArgError(`"state" is one of active, archived, all`)
+      const tags = strings(args, "tags")
+      const project = optional(args, "project")
+      const metadata = record(args, "metadata")
+      const limit = int(args, "limit", 1, 200)
+      const cursor = optional(args, "cursor")
+      if (args.paused !== undefined && typeof args.paused !== "boolean") throw new ArgError(`"paused" must be true or false`)
+      const page = await hub.teams.list({
+        signal,
+        ...(state ? { state: state as "active" | "archived" | "all" } : {}),
+        ...(tags ? { tags } : {}),
+        ...(project ? { project } : {}),
+        ...(metadata ? { metadata } : {}),
+        ...(typeof args.paused === "boolean" ? { paused: args.paused } : {}),
+        ...(limit !== undefined ? { limit } : {}),
+        ...(cursor ? { cursor } : {}),
+      })
+      if (page.items.length === 0) return "no teams"
+      return [...page.items.map(teamLine), ...(page.cursor ? [`more: cursor ${page.cursor}`] : [])].join("\n")
+    },
+  },
+  {
+    name: "team_show",
+    description: `One team: its published definition (mode, entry role, roles, communication paths, tags, projects, metadata), revision, and the pending draft if any. ${SCOPES}`,
+    properties: { team: TEAM },
+    required: ["team"],
+    readOnly: true,
+    run: async (hub, args, signal) => {
+      const { team, draft } = await hub.teams.get(need(args, "team"), { signal })
+      return [teamLine(team), ...specLines(team), ...(draft ? [`draft pending (on v${draft.baseVersion}, saved ${when(draft.savedAt)}): see team_diff`] : [])].join("\n")
+    },
+  },
+  {
+    name: "team_status",
+    description: `A team's state, roster (each role's seats with session, presence, generation and revision; vacant/understaffed roles; launches) and intake counts. ${SCOPES}`,
+    properties: { team: TEAM },
+    required: ["team"],
+    readOnly: true,
+    run: async (hub, args, signal) => {
+      const { team, roster, intake } = await hub.teams.status(need(args, "team"), { signal })
+      const lines = [teamLine(team), ...rosterLines(roster)]
+      if (intake)
+        lines.push(
+          `intake: ${intake.queued} queued, ${intake.routed} routed (${intake.open} open, ${intake.inProgress} in progress, ${intake.blocked} blocked), ${intake.done} done, ${intake.failed} failed, ${intake.cancelled} cancelled${intake.oldestQueuedAt !== undefined ? `; oldest queued ${when(intake.oldestQueuedAt)}` : ""}`,
+        )
+      return lines.join("\n")
+    },
+  },
+  {
+    name: "team_history",
+    description: `A team's retained published versions, newest first (version, digest, when). ${SCOPES}`,
+    properties: { team: TEAM, cursor: STRING },
+    required: ["team"],
+    readOnly: true,
+    run: async (hub, args, signal) => {
+      const cursor = optional(args, "cursor")
+      const page = await hub.teams.versions(need(args, "team"), { signal, ...(cursor ? { cursor } : {}) })
+      return [...page.items.map((v) => `v${v.version}  ${v.digest.slice(0, 12)}  ${when(v.publishedAt)}`), ...(page.cursor ? [`more: cursor ${page.cursor}`] : [])].join("\n")
+    },
+  },
+  {
+    name: "team_diff",
+    description: `What changed between two versions, or from a version (default: the published one) to the draft (default). Names and keys only. ${SCOPES}`,
+    properties: { team: TEAM, from: { type: "integer", minimum: 1 }, to: { description: "A version number or \"draft\" (default)." } },
+    required: ["team"],
+    readOnly: true,
+    run: async (hub, args, signal) => {
+      const from = int(args, "from", 1, 1e9)
+      const to = args.to === undefined || args.to === null || args.to === "draft" ? "draft" : int(args, "to", 1, 1e9)!
+      const { from: a, to: b, diff } = await hub.teams.diff(need(args, "team"), { signal, ...(from !== undefined ? { from } : {}), to })
+      const part = (label: string, d: { added?: readonly string[]; removed?: readonly string[]; changed?: readonly string[] }) =>
+        (["added", "removed", "changed"] as const).flatMap((k) => (d[k]?.length ? [`${label} ${k}: ${d[k]!.join(", ")}`] : []))
+      const lines = [
+        ...(diff.fields.length ? [`fields changed: ${diff.fields.join(", ")}`] : []),
+        ...part("roles", diff.roles),
+        ...part("paths", diff.edges),
+        ...part("tags", diff.tags),
+        ...part("metadata", diff.metadata),
+        ...part("projects", diff.projects),
+      ]
+      return [`v${a} → ${b === "draft" ? "draft" : `v${b}`}`, ...(lines.length ? lines : ["no changes"])].join("\n")
+    },
+  },
+
+  // ---------- definitions ----------
+  {
+    name: "team_create",
+    description: `Assemble a persistent team: roles (one is the entry role that receives submitted work, e.g. a project manager), open or restricted communication with one-way/two-way paths, tags, projects and metadata. Published as version 1 at once; the name is the team's address (@@role#name) and never changes. ${SCOPES}`,
+    properties: { name: { ...STRING, description: "A slug (2–40 lowercase letters, digits, dashes), unique per user." }, ...SPEC_FIELDS, idempotencyKey: IDEMPOTENCY },
+    required: ["name", "title", "mode", "roles", "entryRole"],
+    readOnly: false,
+    organizes: true,
+    idempotent: true,
+    run: async (hub, args, signal) => {
+      need(args, "name")
+      need(args, "title")
+      const key = optional(args, "idempotencyKey")
+      const spec = picked(args, ["name", "title", "description", "mode", "roles", "entryRole", "edges", "tags", "metadata", "projects"]) as unknown as TeamSpec
+      const { team, created } = await hub.teams.create({ ...spec, edges: spec.edges ?? [] }, { signal, ...(key ? { idempotencyKey: key } : {}) })
+      return [`${created ? "created" : "already created (same key)"}: ${teamLine(team)}`, ...specLines(team)].join("\n")
+    },
+  },
+  {
+    name: "team_update",
+    description: `Save changes to a team's draft: title, description, mode, entry role, roles and paths (wholesale lists), tags, metadata, projects (null clears an optional field). Nothing applies until team_publish. ${SCOPES}`,
+    properties: { team: TEAM, ...SPEC_FIELDS, expectedRevision: REVISION },
+    required: ["team", "expectedRevision"],
+    readOnly: false,
+    organizes: true,
+    idempotent: true,
+    run: async (hub, args, signal) => {
+      const expectedRevision = revision(args)
+      const patch = picked(args, ["title", "description", "mode", "roles", "entryRole", "edges", "tags", "metadata", "projects"]) as TeamPatch
+      if (Object.keys(patch).length === 0) throw new ArgError("give at least one field to change")
+      const id = need(args, "team")
+      const { team } = await hub.teams.update(id, patch, expectedRevision, { signal })
+      return draftText("draft saved", team, (await hub.teams.draft(team.id, { signal })).draft)
+    },
+  },
+  draftTool("team_role_set", "Add a role to a team's draft, or replace the role of that name (all its fields).", { role: { ...STRING, description: "The role's name (a slug)." }, ...ROLE_FIELDS }, ["role"], (teams, team, args, rev, signal) =>
+    teams.setRole(team, { name: need(args, "role"), ...picked(args, Object.keys(ROLE_FIELDS)) } as TeamRole, rev, { signal }),
+  ),
+  draftTool("team_role_remove", "Remove a role (not the entry role) and every path touching it from a team's draft.", { role: STRING }, ["role"], (teams, team, args, rev, signal) => teams.removeRole(team, need(args, "role"), rev, { signal })),
+  draftTool("team_edge_set", "Draw a communication path from one role to another in a team's draft (replaces the path drawn between them).", { from: STRING, to: STRING, kinds: KINDS, direction: DIRECTION }, ["from", "to", "kinds", "direction"], (teams, team, args, rev, signal) => {
+    const kinds = strings(args, "kinds")
+    if (!kinds?.length) throw new ArgError(`"kinds" is a list of msg and/or ask`)
+    const direction = need(args, "direction")
+    return teams.setEdge(team, { from: need(args, "from"), to: need(args, "to"), kinds: kinds as TeamEdge["kinds"], direction: direction as TeamEdge["direction"] }, rev, { signal })
+  }),
+  draftTool("team_edge_remove", "Remove the path drawn from one role to another (or a two-way path between them) from a team's draft.", { from: STRING, to: STRING }, ["from", "to"], (teams, team, args, rev, signal) => teams.removeEdge(team, need(args, "from"), need(args, "to"), rev, { signal })),
+  {
+    name: "team_discard_draft",
+    description: `Drop a team's pending draft (unpublished edits are lost; the published version stays). ${SCOPES}`,
+    properties: { team: TEAM, expectedRevision: REVISION },
+    required: ["team", "expectedRevision"],
+    readOnly: false,
+    idempotent: true,
+    run: async (hub, args, signal) => `draft discarded: ${teamLine((await hub.teams.discardDraft(need(args, "team"), revision(args), { signal })).team)}`,
+  },
+  {
+    name: "team_publish",
+    description: `Publish a team's draft as its next version: delivery enforces the new communication policy from the next message, and staffing uses the new roles. Refused while sessions are staffed in a role the draft removes. ${SCOPES}`,
+    properties: { team: TEAM, expectedRevision: REVISION },
+    required: ["team", "expectedRevision"],
+    readOnly: false,
+    idempotent: true,
+    run: async (hub, args, signal) => {
+      const { team, published } = await hub.teams.publish(need(args, "team"), revision(args), { signal })
+      return `${published ? `published version ${team.version}` : "the draft equalled the published version; dropped"}: ${teamLine(team)}`
+    },
+  },
+  statusTool("pause", "Pause a team: it takes no new intake and no new members; its communication policy still applies.", true),
+  statusTool("resume", "Resume a paused team (queued intake is routed again).", true),
+  statusTool("archive", "Archive a team: its policy no longer applies and it takes no work; seats are kept; reversible with team_restore.", false),
+  statusTool("restore", "Restore an archived team: its policy applies again.", false),
+
+  // ---------- staffing ----------
+  {
+    name: "team_staff",
+    description: `Staff a role: attach an existing session (sessionID, any machine) or launch a new member (launch: a launch spec as the launch tool takes). An agent needs the user's grants (roles for the session's project; launch for a repo) or the hub answers needs_user; staffing never issues grants. ${SCOPES}`,
+    properties: { team: TEAM, role: STRING, sessionID: { ...STRING, description: "An existing session (ses_…)." }, launch: { type: "object", description: "A launch spec (repo, harness, model, prompt, …)." }, idempotencyKey: IDEMPOTENCY },
+    required: ["team", "role"],
+    readOnly: false,
+    run: async (hub, args, signal) => {
+      const team = need(args, "team")
+      const role = need(args, "role")
+      const sessionID = optional(args, "sessionID")
+      const launch = launchOf(args)
+      if ((sessionID === undefined) === (launch === undefined)) throw new ArgError(`give exactly one of sessionID or launch`)
+      const key = optional(args, "idempotencyKey")
+      const options = { signal, ...(key ? { idempotencyKey: key } : {}) }
+      if (sessionID !== undefined) {
+        const r = await hub.teams.staff(team, { role, sessionID }, options)
+        return `${r.created ? "staffed" : "already staffed"} ${r.staffing.sessionID} as ${r.staffing.role} (${r.staffing.id}, generation ${r.staffing.generation}, r${r.staffing.revision})${r.workspace ? `; workspace ${r.workspace.id}` : ""}`
+      }
+      const r = await hub.teams.launchMember(team, { role, launch: launch! }, options)
+      return `${r.created ? "launching" : "already launching"} a ${role} member: request ${r.request.id} ${r.request.state}, launch ${r.launch.id} ${r.launch.state}`
+    },
+  },
+  {
+    name: "team_unstaff",
+    description: `End a seat (the session leaves the role and loses the team's policy rights). Send the seat's revision (team_status). ${SCOPES}`,
+    properties: { team: TEAM, staffingID: { ...STRING, description: "The seat (stf_…)." }, expectedRevision: { ...REVISION, description: "The seat's revision you read (team_status)." } },
+    required: ["team", "staffingID", "expectedRevision"],
+    readOnly: false,
+    idempotent: true,
+    run: async (hub, args, signal) => {
+      const { staffing } = await hub.teams.unstaff(need(args, "team"), need(args, "staffingID"), revision(args), { signal })
+      return `unstaffed ${staffing.id} (${staffing.sessionID} as ${staffing.role})`
+    },
+  },
+  {
+    name: "team_replace",
+    description: `Replace a seat by an existing session (sessionID) or a new launch (launch): the old seat ends at once and the new member gets the slot's next generation. Send the seat's revision (team_status). ${SCOPES}`,
+    properties: { team: TEAM, staffingID: STRING, sessionID: STRING, launch: { type: "object" }, expectedRevision: { ...REVISION, description: "The seat's revision you read (team_status)." } },
+    required: ["team", "staffingID", "expectedRevision"],
+    readOnly: false,
+    run: async (hub, args, signal) => {
+      const expectedRevision = revision(args)
+      const sessionID = optional(args, "sessionID")
+      const launch = launchOf(args)
+      if ((sessionID === undefined) === (launch === undefined)) throw new ArgError(`give exactly one of sessionID or launch`)
+      const input = sessionID !== undefined ? { expectedRevision, sessionID } : { expectedRevision, launch: launch! }
+      const r = await hub.teams.replace(need(args, "team"), need(args, "staffingID"), input, { signal })
+      const next = r.staffing ? `${r.staffing.sessionID} (${r.staffing.id}, generation ${r.staffing.generation})` : `launch ${r.launch?.id ?? "?"} (request ${r.request?.id ?? "?"})`
+      return `replaced ${r.ended.sessionID} in ${r.ended.role} by ${next}`
+    },
+  },
+]