@huynle/hub 0.7.4 → 0.8.1

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

@@ -0,0 +1,460 @@
+// 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
+// (FX-03, l3vynemo) The launch spec as validateLaunchSpec (src/central/agent/launch-spec.ts) takes it: NESTED sections,
+// unlike the plain launch tool's flat fields. Keep the two in step. No additionalProperties: false, so a flat field
+// reaches the hub, whose answer names the nested place it belongs (a client-side schema refusal would not).
+const LAUNCH = {
+  type: "object",
+  description:
+    "A launch spec (nested, as POST /api/agent/launches takes; unlike the launch tool's flat fields): workspace{repo, mode, branch, base, remote} is required; placement{machine, labels, mode}, runtime{kind, profile}, end{when, timeout, cleanup} and the top-level fields are optional; key is set by staffing (send idempotencyKey instead). The role's prefs fill harness, model and placement.machine, and its profile fills agentProfile, when not given. A flat field (repo, machine, cleanup at the top) is refused with the nested place it belongs.",
+  properties: {
+    workspace: {
+      type: "object",
+      description: "Where the member works on its machine.",
+      properties: {
+        repo: { ...STRING, description: "The repository's absolute path on the machine." },
+        mode: { type: "string", enum: ["worktree", "checkout", "clone"], description: "worktree (default; needs branch), checkout, or clone (needs remote)." },
+        branch: { ...STRING, description: "The branch to create or check out (a safe git branch name; required for worktree)." },
+        base: { ...STRING, description: "What a new branch starts from." },
+        remote: { ...STRING, description: "An https or ssh git remote, without credentials (required for clone)." },
+      },
+      required: ["repo"],
+    },
+    placement: {
+      type: "object",
+      description: "Which machine runs it.",
+      properties: {
+        machine: { ...STRING, description: "A machine ID or name." },
+        labels: { type: "object", additionalProperties: STRING, description: "Node labels to match." },
+        mode: { type: "string", enum: ["require", "prefer"], description: "require (default) or prefer the machine/labels." },
+      },
+    },
+    runtime: {
+      type: "object",
+      properties: {
+        kind: { type: "string", enum: ["host", "openshell"], description: "host (default) or openshell (clone workspaces only)." },
+        profile: { ...STRING, description: "An openshell sandbox profile (openshell only)." },
+      },
+    },
+    end: {
+      type: "object",
+      description: "When the launch ends.",
+      properties: {
+        when: { type: "string", enum: ["idle", "asked", "never"], description: "idle (default), asked or never." },
+        timeout: { type: ["string", "number"], description: "1 minute to 30 days: seconds, or 30m, 4h, 2d." },
+        cleanup: { type: "string", enum: ["keep", "remove"], description: "keep (default) or remove the workspace at the end." },
+      },
+    },
+    name: { ...STRING, description: "The session's @name, without the @." },
+    roles: { ...STRINGS, description: "Roles the session claims (up to 10)." },
+    harness: { ...STRING, description: "The harness (default opencode)." },
+    agent: { ...STRING, description: "The harness agent." },
+    model: { ...STRING, description: "provider/model." },
+    prompt: { ...STRING, description: "The first prompt (up to 10000 characters)." },
+    intent: { ...STRING, description: "What the session is for (one line)." },
+    labels: { type: "object", additionalProperties: STRING, description: "Free-form app labels." },
+    agentProfile: { type: "object", properties: { profileID: STRING, version: { type: "integer", minimum: 1 } }, required: ["profileID", "version"], description: "The profile version to pin (needs profiles:assign for an app)." },
+  },
+  required: ["workspace"],
+} 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: LAUNCH, 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: LAUNCH, 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}`
+    },
+  },
+]

package/packages/cli/src/watchlist.ts

@@ -0,0 +1,135 @@
+// `hub watchlist [show|watch|unwatch|mute|unmute] <addr>` and the MCP tools watchlist_get, watchlist_update,
+// watchlist_watch and watchlist_mute (CON-01): the Concierge's watchlist over /api/agent/concierge/watchlist. Users and
+// app tokens (sessions:read to show, sessions:manage to change); the user's current Concierge session through its
+// act token (show and the verbs). Other session tokens get not found (exit 3).
+import { sanitizeLabel } from "../../sdk/src/envelope.ts"
+import type { Concierge, WatchlistChanged, WatchlistConfig, WatchlistUpdate, WatchlistView } from "../../sdk/src/index.ts"
+
+type Args = Record<string, unknown>
+
+/** The shape of an MCP tool (as packages/cli/src/mcp.ts registers them). */
+export interface WatchlistTool {
+  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 concierge: Concierge }, args: Args, signal: AbortSignal): Promise<string>
+}
+
+/** One value from the hub, safe to print: escapes, control, bidi and zero-width characters removed, one line. */
+const safe = (value: unknown) => sanitizeLabel(String(value), 1024)
+const list = (items: readonly string[]) => (items.length ? items.map(safe).join(", ") : "none")
+
+export function watchlistConfigText(c: WatchlistConfig): string {
+  return [
+    `revision ${safe(c.revision)}`,
+    `auto-active: ${c.autoActive ? `on (within ${safe(c.activeWithinHours)} h)` : "off"}  pins: ${c.usePins ? "on" : "off"}`,
+    `sessions: ${list(c.sessions)}`,
+    `projects: ${list(c.projects)}`,
+    `labels: ${c.labels.length ? c.labels.map((l) => Object.entries(l).map(([k, v]) => `${safe(k)}=${safe(v)}`).join(",")).join("; ") : "none"}`,
+    `muted: ${list(c.muted)}`,
+    `muted projects: ${list(c.mutedProjects)}`,
+  ].join("\n")
+}
+
+export function watchlistText(view: WatchlistView): string {
+  const rows = view.entries.map((e) => `${safe(e.sessionID)}  ${e.reasons.map(safe).join(",")}${e.lastActiveAt !== undefined ? `  active ${new Date(e.lastActiveAt).toISOString()}` : ""}`)
+  return [watchlistConfigText(view.config), "", view.entries.length ? `watching ${view.entries.length}${view.truncated ? " (truncated)" : ""}:` : "watching nothing", ...rows].join("\n")
+}
+
+export function watchlistChangedText(verb: string, r: WatchlistChanged): string {
+  return `${r.changed ? `${verb}` : `already ${verb}`}: ${safe(r.sessionID)} (revision ${safe(r.config.revision)})`
+}
+
+const PAST: Record<string, string> = { watch: "watching", unwatch: "not watching", mute: "muted", unmute: "unmuted" }
+export const watchlistVerbText = (verb: "watch" | "unwatch" | "mute" | "unmute", r: WatchlistChanged) => watchlistChangedText(PAST[verb]!, r)
+
+const ADDR = { type: "string", description: "Session address: ses_… (or a unique prefix), @name, @@role, @name.project." } as const
+const STRINGS = { type: "array", items: { type: "string" } } as const
+
+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 flag = (args: Args, key: string, fallback: boolean): boolean => {
+  const value = args[key]
+  if (value === undefined || value === null) return fallback
+  if (typeof value !== "boolean") throw new Error(`"${key}" must be true or false`)
+  return value
+}
+
+const UPDATE_FIELDS = ["autoActive", "activeWithinHours", "usePins", "sessions", "projects", "labels", "muted", "mutedProjects"] as const
+
+export const watchlistTools: readonly WatchlistTool[] = [
+  {
+    name: "watchlist_get",
+    description: "The Concierge's watchlist: its config (revision) and the sessions it watches now, with why (active, pinned, pinned_project, explicit, project, label). Needs sessions:read for an app token.",
+    properties: {},
+    readOnly: true,
+    run: async (hub, _args, signal) => watchlistText(await hub.concierge.watchlist.get({ signal })),
+  },
+  {
+    name: "watchlist_update",
+    description:
+      "Change the watchlist config under the revision you read (expectedRevision; a stale one is a conflict). Give only the fields to change: autoActive, activeWithinHours (1–24), usePins, sessions (ses_… IDs), projects (absolute dirs), labels ([{key: value}]), muted, mutedProjects. Users and app tokens with sessions:manage.",
+    properties: {
+      expectedRevision: { type: "integer", minimum: 0 },
+      autoActive: { type: "boolean" },
+      activeWithinHours: { type: "integer", minimum: 1, maximum: 24 },
+      usePins: { type: "boolean" },
+      sessions: STRINGS,
+      projects: STRINGS,
+      labels: { type: "array", items: { type: "object", additionalProperties: { type: "string" } } },
+      muted: STRINGS,
+      mutedProjects: STRINGS,
+    },
+    required: ["expectedRevision"],
+    readOnly: false,
+    organizes: true,
+    run: async (hub, args, signal) => {
+      const expected = args.expectedRevision
+      if (typeof expected !== "number" || !Number.isSafeInteger(expected) || expected < 0) throw new Error(`"expectedRevision" is required (the revision you read)`)
+      const unknown = Object.keys(args).filter((k) => k !== "expectedRevision" && !(UPDATE_FIELDS as readonly string[]).includes(k))
+      if (unknown.length) throw new Error(`Unknown argument${unknown.length > 1 ? "s" : ""} ${unknown.map((k) => `"${safe(k).slice(0, 40)}"`).join(", ")}: use ${UPDATE_FIELDS.join(", ")} and expectedRevision`)
+      const patch: Record<string, unknown> = {}
+      for (const field of UPDATE_FIELDS) if (args[field] !== undefined && args[field] !== null) patch[field] = args[field]
+      const r = await hub.concierge.watchlist.update(patch as WatchlistUpdate, expected, { signal })
+      const head = r.config.revision === expected ? `No change (revision ${safe(expected)})` : `Updated the watchlist (revision ${safe(expected)} → ${safe(r.config.revision)})`
+      return `${head}\n${watchlistConfigText(r.config)}`
+    },
+  },
+  {
+    name: "watchlist_watch",
+    description: "Watch a session (watch: false stops watching it). A subagent watches its root. Idempotent; grants nothing.",
+    properties: { addr: ADDR, watch: { type: "boolean", description: "Default true; false unwatches." } },
+    required: ["addr"],
+    readOnly: false,
+    organizes: true,
+    idempotent: true,
+    run: async (hub, args, signal) => {
+      const on = flag(args, "watch", true)
+      const addr = need(args, "addr")
+      const r = on ? await hub.concierge.watchlist.watch(addr, { signal }) : await hub.concierge.watchlist.unwatch(addr, { signal })
+      return watchlistVerbText(on ? "watch" : "unwatch", r)
+    },
+  },
+  {
+    name: "watchlist_mute",
+    description: "Mute a session in the watchlist (mute: false unmutes it): a muted session is never watched, whatever includes it. Not a notification mute. Idempotent.",
+    properties: { addr: ADDR, mute: { type: "boolean", description: "Default true; false unmutes." } },
+    required: ["addr"],
+    readOnly: false,
+    organizes: true,
+    idempotent: true,
+    run: async (hub, args, signal) => {
+      const on = flag(args, "mute", true)
+      const addr = need(args, "addr")
+      const r = on ? await hub.concierge.watchlist.mute(addr, { signal }) : await hub.concierge.watchlist.unmute(addr, { signal })
+      return watchlistVerbText(on ? "mute" : "unmute", r)
+    },
+  },
+]

package/packages/codex/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-codex",
-  "version": "0.7.4",
+  "version": "0.8.1",
   "private": true,
   "description": "The Codex app-server spoke: attaches to Codex's app-server (its own over stdio, and the shared daemon's socket when present), and the `hub codex` wrapper (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/codex/src/paths.ts

@@ -1,12 +1,12 @@
 // Where the Codex spoke looks and keeps its files. It only reads Codex's home (CODEX_HOME, default ~/.codex) to find
 // the shared daemon's socket; its own files live in <hub state dir>/codex (the hub state dir is $HUB_STATE_DIR, else
-// ~/.local/state/hub), a private (0700) directory holding the service's pid file (spoke.pid) and its log.
+// $XDG_STATE_HOME/hub or ~/.local/state/hub), a private (0700) directory holding the service's pid file (spoke.pid) and its log.
 // $HUB_CODEX_DAEMON_SOCKET names another daemon socket, or "off" for none.
 import { chmodSync, lstatSync, mkdirSync, readFileSync } from "node:fs"
 import { homedir } from "node:os"
 import path from "node:path"
 import { hubEnv, type Env } from "../../../src/env.ts"
-import { APP_DIR, stateBase } from "../../../src/migrate.ts"
+import { resolveHubStateDir } from "../../../src/migrate.ts"
 
 export function codexHome(env: Env = process.env, home: string = homedir()): string {
   return env.CODEX_HOME || path.join(home, ".codex")
@@ -20,7 +20,7 @@ export function daemonSocketPath(env: Env = process.env, home: string = homedir(
 }
 
 export function codexStateDir(env: Env = process.env, home: string = homedir()): string {
-  return path.join(hubEnv(env).HUB_STATE_DIR || path.join(stateBase(home), APP_DIR), "codex")
+  return path.join(resolveHubStateDir(env, home).dir, "codex")
 }
 
 export const pidFile = (env: Env = process.env, home: string = homedir()) => path.join(codexStateDir(env, home), "spoke.pid")