@huynle/hub 0.7.4 → 0.8.1

package/packages/cli/src/login.ts

@@ -4,12 +4,13 @@
 // out an app token of that user, once.
 //
 // Policy (the machine enrollment's, packages/cli/src/bootstrap/enrollment/policy.ts):
-// - The hub URL is https (plain http only for a loopback hub); redirects are refused, never followed.
-// - The approval link shown is on the hub's own origin (approvalURL).
+// - The hub URL is https (plain http only for a loopback hub, or with allowInsecureHTTP a private-network IP address,
+//   with a warning each time); redirects are refused, never followed.
+// - The approval link shown is on the hub's own origin, or a loopback hub's public URL (approvalURL).
 // - The wait is bounded by the hub's expiry and by maxWaitMs; `signal` cancels it.
 // - The token is returned to the caller only, never printed. A poll that fails in transit is retried until the
 //   deadline (a reply lost after the hub handed the token out cannot be fetched again: the user revokes that token).
-import { approvalURL, checkServerURL, isUserCode } from "./bootstrap/enrollment/policy.ts"
+import { approvalURL, checkServerURL, insecureHTTPRefusal, insecureHTTPWarning, isLoopbackServer, isPlainHTTP, isUserCode, shownURL } from "./bootstrap/enrollment/policy.ts"
 import { UsageError } from "./args"
 import { CliError, EXIT } from "./http"
 
@@ -26,6 +27,10 @@ export interface LoginPrompt {
   /** The scopes the approval page offers ticked. */
   readonly scopes: readonly string[]
   readonly warning?: string
+  /** A loopback hub's own link on this machine, when approveURL is its public URL. */
+  readonly localURL?: string
+  /** Plain http to a private-network hub (--allow-insecure-http): said every time. */
+  readonly insecure?: string
 }
 
 export interface DeviceLoginOptions {
@@ -34,6 +39,8 @@ export interface DeviceLoginOptions {
   readonly clientName: string
   /** Asked for beyond the hub's defaults (sessions:read, messages:send, messages:read). */
   readonly scopes?: readonly string[]
+  /** --allow-insecure-http: also plain http to a private-network IP address (with a warning). Never stored. */
+  readonly allowInsecureHTTP?: boolean
   readonly fetch?: typeof fetch
   readonly signal?: AbortSignal
   readonly now?: () => number
@@ -90,8 +97,13 @@ const hubMessage = (body: unknown): string | undefined => (isRecord(body) && isR
 
 /** Runs the device-code login: the approved app token, or a CliError (nothing to store). */
 export async function deviceLogin(options: DeviceLoginOptions): Promise<DeviceLogin> {
-  const server = checkServerURL(options.server)
-  if (!server) throw new UsageError(`the hub URL must be https (plain http only for a loopback hub), without user info, query or fragment: ${String(options.server).slice(0, 200)}`)
+  const allow = { allowInsecureHTTP: options.allowInsecureHTTP === true }
+  const server = checkServerURL(options.server, allow)
+  if (!server) {
+    const why = insecureHTTPRefusal(options.server, allow)
+    throw new UsageError(why ? `${why}: ${shownURL(String(options.server))}` : `the hub URL must be https (plain http only for a loopback hub), without user info, query or fragment: ${shownURL(String(options.server))}`)
+  }
+  const insecure = isPlainHTTP(server) && !isLoopbackServer(server) ? insecureHTTPWarning(server) : undefined
   const fetcher = options.fetch ?? fetch
   const now = options.now ?? Date.now
   const { signal } = options
@@ -106,7 +118,7 @@ export async function deviceLogin(options: DeviceLoginOptions): Promise<DeviceLo
   }
   const link = approvalURL(server, start.approveURL, start.userCode)
   const expiresAt = Math.min(start.expiresAt as number, now() + (options.maxWaitMs ?? LOGIN_MAX_WAIT_MS))
-  options.onPrompt?.({ userCode: start.userCode, approveURL: link.url, expiresAt, scopes: stringList(start.scopes) ?? [], ...(link.warning ? { warning: link.warning } : {}) })
+  options.onPrompt?.({ userCode: start.userCode, approveURL: link.url, expiresAt, scopes: stringList(start.scopes) ?? [], ...(link.warning ? { warning: link.warning } : {}), ...(link.localURL ? { localURL: link.localURL } : {}), ...(insecure ? { insecure } : {}) })
 
   const interval = options.intervalMs ?? Math.min(Math.max(start.intervalMs as number, MIN_INTERVAL_MS), MAX_INTERVAL_MS)
   for (;;) {
@@ -140,8 +152,10 @@ export async function deviceLogin(options: DeviceLoginOptions): Promise<DeviceLo
 export function promptText(prompt: LoginPrompt): string {
   const minutes = Math.max(1, Math.round((prompt.expiresAt - Date.now()) / 60_000))
   return [
+    ...(prompt.insecure ? [`hub: warning: ${prompt.insecure}`] : []),
     ...(prompt.warning ? [`hub: warning: ${prompt.warning}`] : []),
     `To log in, open ${prompt.approveURL}`,
+    ...(prompt.localURL ? [`(on this machine: ${prompt.localURL})`] : []),
     `and approve code ${prompt.userCode} as yourself (expires in ${minutes} min; Ctrl-C cancels).`,
     ...(prompt.scopes.length ? [`Requested scopes: ${prompt.scopes.join(", ")} (you choose on the page).`] : []),
     "Waiting for approval…",

package/packages/cli/src/mcp.ts

@@ -2,17 +2,32 @@
 // the CLI keeps no dependencies. It answers initialize, ping, tools/list and tools/call; notifications get no answer.
 // The tools are the CLI's verbs: reading, messaging, the act verbs (approve, deny, answer, prompt, stop; an app
 // token needs scope sessions:act and a grant) and launches (launch, launches, launch_show, launch_stop; an app
-// token needs scope sessions:launch and a launch grant).
+// token needs scope sessions:launch and a launch grant), and artifacts (artifacts, artifact_show, artifact_publish,
+// artifact_revise; scopes artifacts:read|write, by reference: packages/cli/src/artifacts-mcp.ts), artifact AI jobs
+// (artifact_job_request, artifact_jobs, artifact_job, artifact_job_context, artifact_job_result, artifact_job_apply,
+// artifact_job_cancel; scope artifacts:ai: packages/cli/src/artifact-jobs-mcp.ts), and team intake
+// (team_submit, team_intake, team_intake_update; scope teams:submit: packages/cli/src/team-intake-mcp.ts), and teams
+// (teams, team_show, team_status, team_create, team_publish, team_staff, …; scopes teams:read|manage: teams-mcp.ts),
+// the profile lifecycle (profile_show, profile_create, profile_update, profile_version_create, profile_skill_set, …,
+// profile_assign; scopes profiles:read|manage|assign: profiles-mcp.ts), and the Concierge watchlist (watchlist_get,
+// watchlist_update, watchlist_watch, watchlist_mute: watchlist.ts).
 import { renderEnvelope, sanitizeText, WAIT_POLL_MAX_S, type AgentMessage, type Asked, type DecisionState, type FormAnswer, type HubClient, type LaunchSpec, type LaunchState, type PromptDelivery, type Inbox, type Sent, type SentAll } from "../../sdk/src/index.ts"
 import { answeredText, approvedText, DELIVERIES, deniedText, needsUserLines, promptedText, stoppedText } from "./acting"
 import { UsageError } from "./args"
+import { intentLine, writeIntent } from "./intents"
 import type { Credentials } from "./credentials"
 import { logText, oneLine, sessionsText, showText, statusText, whoamiText, whoText } from "./format"
 import { CliError, withHub } from "./http"
-import { askOutcome, declinedText, durationArg, mutedText, repliedText, sentText } from "./messaging"
+import { askOutcome, declinedText, deliveryText, durationArg, mutedText, repliedText, sentText } from "./messaging"
 import { DECISION_STATES, decisionsText, decisionText, openedText } from "./decisions"
 import { CLEANUP_POLICIES, LAUNCH_END_WHEN, RUNTIME_KINDS, WORKSPACE_MODES } from "../../protocol/src/launch.ts"
 import { launchedText, launchesText, launchText, stoppedLaunchText } from "./launches"
+import { artifactTools } from "./artifacts-mcp"
+import { artifactJobTools } from "./artifact-jobs-mcp"
+import { teamIntakeTools } from "./team-intake-mcp"
+import { teamTools } from "./teams-mcp"
+import { ProfileArgError, profileLifecycleTools } from "./profiles-mcp"
+import { watchlistTools } from "./watchlist"
 
 /** The protocol revisions the server speaks, newest first: a client's supported one is echoed, else the newest. */
 export const MCP_PROTOCOL_VERSIONS: readonly string[] = ["2025-06-18", "2025-03-26", "2024-11-05"]
@@ -192,7 +207,8 @@ function inboxText(box: Inbox): string {
 
 /** One message (message_show): its state, the message and, once answered or declined, the answer, in envelopes. */
 function messageText({ message, answer }: Asked): string {
-  const lines = [NOT_FROM_USER, `${message.kind} ${message.id}: ${message.state}`, envelope(message)]
+  // (CON-10) A message dropped for a recipient that ended for good says so.
+  const lines = [NOT_FROM_USER, `${message.kind} ${message.id}: ${message.state}${message.delivery === "dropped" || message.delivery === "expired" ? ` · ${deliveryText(message.delivery)}` : ""}`, envelope(message)]
   if (answer) lines.push(`${message.state} by ${answer.id}:`, envelope(answer))
   return lines.join("\n")
 }
@@ -205,7 +221,7 @@ const SEND = {
   urgent: { type: "boolean", description: "Steer into the recipient's running turn." },
   all: { type: "boolean", description: "Send to every session the address names (each holder of a role)." },
 } as const
-const TO = { type: "string", description: "The recipient: @name, @@role, @name.project, ses_…, or @me (the user)." } as const
+const TO = { type: "string", description: "The recipient: @name, @@role, @@role#team (a role of one of your teams), @name.project, ses_…, or @me (the user)." } as const
 const MSG_ID = { type: "string", description: "The ID (msg_…) of the message you answer." } as const
 const ADDR = { type: "string", description: "A session: ses_… (or an unambiguous prefix), @name, @@role or @name.project." } as const
 const WHY = { type: "string", description: "Why: recorded in the agent audit (and for deny, passed to the harness)." } as const
@@ -262,6 +278,34 @@ const archiveInactiveTool: Tool = {
   },
 }
 
+const intentTools: readonly Tool[] = [
+  {
+    name: "session_intent_get",
+    description: "What a session is for: its intent (user, launch, self, first prompt; else its title), as untrusted one-line text. Needs sessions:read for an app token.",
+    properties: { addr: ADDR },
+    required: ["addr"],
+    readOnly: true,
+    run: async (hub, args, signal) => intentLine(need(args, "addr"), (await hub.intent(need(args, "addr"), { signal })).intent),
+  },
+  {
+    name: "session_intent_set",
+    description: "Set (text, one line, at most 280 characters) or clear (clear: true) a session's intent. Users and apps (sessions:manage) set the user's intent; a session token only its own session's. expectedRevision: the revision read (read first when absent); a stale one is a conflict.",
+    properties: { addr: ADDR, text: STRING, clear: { type: "boolean" }, expectedRevision: { type: "integer", minimum: 0 } },
+    required: ["addr"],
+    readOnly: false,
+    organizes: true,
+    idempotent: true,
+    run: async (hub, args, signal) => {
+      const addr = need(args, "addr")
+      const text = optional(args, "text")
+      const clear = args.clear === true
+      if (clear === (text !== undefined)) throw new ArgError('Give "text" or "clear": true')
+      const expectedRevision = optionalInt(args, "expectedRevision", 0, Number.MAX_SAFE_INTEGER)
+      return intentLine(addr, await writeIntent(hub, addr, clear ? null : text!, { signal, ...(expectedRevision !== undefined ? { expectedRevision } : {}) }))
+    },
+  },
+]
+
 const TARGET = { ...ADDR, description: `${ADDR.description} Required for an app token; a session token defaults to itself.` } as const
 const ROLE = { ...STRING, description: "A role (reviewer, @@reviewer or reviewer.project)." } as const
 const ROLE_PROJECT = { ...STRING, description: "Scope the role to this project (as role.project)." } as const
@@ -271,7 +315,7 @@ const roleText = (r: { role: string; project?: string }) => `@@${r.role}${r.proj
 const nameTools: readonly Tool[] = [
   {
     name: "name",
-    description: `Name a session (@name); its previous name stays an alias for 24 h. A taken name fails (name_taken). ${MANAGE_NOTE}.`,
+    description: `Name a session (@name); as a session, leave addr out to name yourself (a session token names only its own session). Its previous name stays an alias for 24 h. A taken name fails (name_taken); @me is reserved. ${MANAGE_NOTE}.`,
     properties: { addr: TARGET, name: { ...STRING, description: "The name: 2–40 characters a-z, 0-9 and - (a leading @ is fine)." } },
     required: ["name"],
     readOnly: false,
@@ -285,7 +329,7 @@ const nameTools: readonly Tool[] = [
   },
   {
     name: "role_claim",
-    description: `Claim a role for a session; exclusive fails while another session holds it. Reserved roles (orchestrator…) are the user's to assign. ${MANAGE_NOTE}, plus a grant allowing roles on the session's project.`,
+    description: `Claim a role for a session (as a session, leave addr out to claim it yourself so @@role reaches you); exclusive fails while another session holds it. Reserved roles (orchestrator…) are the user's to assign. ${MANAGE_NOTE}, plus a grant allowing roles on the session's project.`,
     properties: { addr: TARGET, role: ROLE, project: ROLE_PROJECT, exclusive: { type: "boolean", description: "Be the only holder." } },
     required: ["role"],
     readOnly: false,
@@ -366,15 +410,338 @@ const webhookTools: readonly Tool[] = [
   },
 ]
 
+/** The session a profile tool reads: `addr`, else the caller's own session (session tokens). */
+async function profileTarget(hub: HubClient, args: Args, signal: AbortSignal): Promise<string> {
+  const addr = optional(args, "addr")
+  if (addr) return addr
+  const { actor } = await hub.whoami({ signal })
+  if (actor.kind !== "session") throw new ArgError(`"addr" is required unless this credential is a session's`)
+  return actor.sessionID
+}
+const optionalParams = (args: Args): Record<string, string> => optionalLabels(args, "params") ?? {}
+const profileTools: readonly Tool[] = [
+  {
+    name: "profile",
+    description: "The profile pinned to a session (your own by default): instructions present, skill and command names with descriptions, never bodies. Load a skill with profile_skill. A profile confers no authority.",
+    properties: { addr: ADDR }, readOnly: true,
+    run: async (hub, args, signal) => {
+      const sessionID = await profileTarget(hub, args, signal)
+      const r = await hub.profiles.ofSession(sessionID, { signal })
+      if (!r.assignment) return `${sessionID} has no profile`
+      const v = r.version
+      const lines = [`${r.assignment.sessionID} pins ${r.assignment.profileID} v${r.assignment.version}${r.profile ? ` (${r.profile.name}: ${oneLine(sanitizeText(r.profile.title))})` : ""}${r.assignment.ack ? `, ack ${r.assignment.ack.status}` : ""}`]
+      if (v) {
+        lines.push(`instructions: ${v.instructions ? "yes" : "no"}`)
+        if (v.skills.length) lines.push("skills:", ...v.skills.map((k) => `  ${k.name}: ${oneLine(sanitizeText(k.description))}`))
+        if (v.commands.length) lines.push("commands:", ...v.commands.map((c) => `  ${c.name}(${c.params.join(", ")}): ${oneLine(sanitizeText(c.description))}`))
+        if (v.secretRefs.length) lines.push(`secret references: ${v.secretRefs.join(", ")}`)
+      } else lines.push("the pinned version is no longer retained")
+      return lines.join("\n")
+    },
+  },
+  {
+    name: "profile_skill",
+    description: "Load one skill's full text from the profile pinned to a session (your own by default), on demand.",
+    properties: { name: STRING, addr: ADDR }, required: ["name"], readOnly: true,
+    run: async (hub, args, signal) => {
+      const r = await hub.profiles.sessionSkill(await profileTarget(hub, args, signal), need(args, "name"), { signal })
+      return `skill ${r.skill.name} (${r.profileID} v${r.version}):\n${sanitizeText(r.skill.body)}`
+    },
+  },
+  {
+    name: "profile_command",
+    description: "Render one command of the profile pinned to a session (your own by default) with its {{name}} parameters. Returns the text only: nothing is sent. {{secret:NAME}} references stay unresolved.",
+    properties: { name: STRING, params: { type: "object", additionalProperties: STRING, description: "Parameter name → text value." }, addr: ADDR }, required: ["name"], readOnly: true,
+    run: async (hub, args, signal) => {
+      const r = await hub.profiles.sessionRender(await profileTarget(hub, args, signal), need(args, "name"), optionalParams(args), { signal })
+      return r.prompt
+    },
+  },
+  {
+    name: "profiles",
+    description: "List the user's profiles (id, name, latest version, state). Needs scope profiles:read for an app token; session tokens read only their own pinned profile (tool profile).",
+    properties: { state: { type: "string", enum: ["active", "archived", "all"] } }, readOnly: true,
+    run: async (hub, args, signal) => {
+      const state = optionalEnum(args, "state", ["active", "archived", "all"] as const)
+      const r = await hub.profiles.list({ ...(state ? { state } : {}), limit: 200, signal })
+      return r.items.length ? r.items.map((p) => `${p.id}  ${p.name}  v${p.latestVersion}  ${p.state}  ${oneLine(sanitizeText(p.title))}`).join("\n") : "no profiles"
+    },
+  },
+  {
+    name: "profile_usage",
+    description:
+      "Where one profile is used: pinned sessions (requested vs running version, ack, presence, harness), team roles naming it, launches that named it and the sessions' workspaces, with counts. An app token needs profiles:read, plus sessions:read / teams:read / sessions:launch (its own launches) / workspaces:read for each part; parts it may not read are listed as hidden.",
+    properties: { id: STRING, limit: { type: "integer", minimum: 1, maximum: 200, description: "Sessions per page (default 50)." }, cursor: STRING }, required: ["id"], readOnly: true,
+    run: async (hub, args, signal) => {
+      const limit = optionalInt(args, "limit", 1, 200)
+      const cursor = optional(args, "cursor")
+      const u = await hub.profiles.usage(need(args, "id"), { ...(limit !== undefined ? { limit } : {}), ...(cursor ? { cursor } : {}), signal })
+      const c = u.counts
+      const plural = (n: number, word: string, many = `${word}s`) => `${n} ${n === 1 ? word : many}`
+      const lines = [`${u.profileID} (latest v${u.latestVersion})`]
+      const summary = [
+        c.sessions !== undefined ? `${plural(c.sessions, "session")} (${c.online ?? 0} online, ${c.olderVersion ?? 0} on older versions)` : "",
+        c.teamRoles !== undefined ? `${plural(c.teamRoles, "team role")}${c.staffedSeats !== undefined ? ` (${c.staffedSeats} staffed seats)` : ""}` : "",
+        c.launches !== undefined ? `${plural(c.launches, "launch", "launches")} (${c.liveLaunches ?? 0} live)` : "",
+        c.workspaces !== undefined ? plural(c.workspaces, "workspace") : "",
+      ].filter(Boolean)
+      if (summary.length) lines.push(summary.join(" · "))
+      for (const s of u.sessions?.items ?? []) {
+        const running = s.effective && s.effective.version !== s.version ? `, running v${s.effective.version}` : ""
+        const who = s.name ? ` @${s.name}` : ""
+        lines.push(`  session ${s.sessionID}${who} v${s.version}${s.olderVersion ? " (older)" : ""}${running}${s.ack ? `, ack ${s.ack.status}` : ""}, ${s.online ? "online" : "offline"}${s.harness ? `, ${s.harness}` : ""}${s.machineID ? ` on ${s.machineID}` : ""}`)
+      }
+      if (u.sessions?.cursor) lines.push(`  more sessions: cursor ${u.sessions.cursor}`)
+      for (const r of u.teamRoles ?? []) lines.push(`  team ${r.teamName} role ${r.role}${r.version !== undefined ? ` v${r.version}` : " (latest)"}${r.staffed !== undefined ? `: ${r.staffed} staffed` : ""}`)
+      for (const l of u.launches ?? []) lines.push(`  launch ${l.id} ${l.state}${l.outcome ? ` (${l.outcome})` : ""} v${l.version}${l.sessionID ? ` → ${l.sessionID}` : ""}`)
+      for (const w of u.workspaces ?? []) lines.push(`  workspace ${w.workspaceID}${w.title ? ` ${oneLine(sanitizeText(w.title))}` : ""}: ${plural(w.sessions, "session")}`)
+      if (u.projects?.length) lines.push(`projects: ${u.projects.map((p) => oneLine(sanitizeText(p))).join(", ")}`)
+      if (u.hidden?.length) lines.push(`hidden: ${u.hidden.join(", ")}`)
+      if (u.truncated?.length) lines.push(`truncated: ${u.truncated.join(", ")}`)
+      return lines.join("\n")
+    },
+  },
+]
+
+/** A required whole-number argument (revisions). */
+const needRevision = (args: Args, key = "expectedRevision"): number => {
+  const value = optionalInt(args, key, 0, Number.MAX_SAFE_INTEGER)
+  if (value === undefined) throw new ArgError(`"${key}" is required: the revision you read`)
+  return value
+}
+const idemOption = (args: Args) => {
+  const key = optional(args, "idempotencyKey")
+  return key !== undefined ? { idempotencyKey: key } : {}
+}
+const WORKSPACE = { type: "string", description: "The workspace's ID (ws_…)." } as const
+const REVISION = { type: "integer", minimum: 0, description: "The revision you read (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 MEMBER_ROLES = ["worker", "observer"] as const
+const ASSIGNMENT_STATUSES = ["open", "in_progress", "blocked", "done", "cancelled"] as const
+const WS_SCOPES = "Needs scope workspaces:read (reads) or workspaces:manage (changes) for an app token; member and assignment tools also need sessions:read. Session tokens are refused. Membership and supervision confer no authority."
+const wsLine = (w: { id: string; state: string; revision: number; title: string }) => `${w.id}  ${w.state}  r${w.revision}  ${oneLine(sanitizeText(w.title))}`
+const workspaceTools: readonly Tool[] = [
+  {
+    name: "workspaces",
+    description: `List the user's coordination workspaces (id, state, revision, title). ${WS_SCOPES}`,
+    properties: { state: { type: "string", enum: ["active", "archived"] } }, readOnly: true,
+    run: async (hub, args, signal) => {
+      const state = optionalEnum(args, "state", ["active", "archived"] as const)
+      const r = await hub.workspaces.list({ ...(state ? { state } : {}), limit: 200, signal })
+      return r.items.length ? r.items.map(wsLine).join("\n") : "no workspaces"
+    },
+  },
+  {
+    name: "workspace_show",
+    description: `One workspace: its record, repo bindings, current members (session, role, presence) and supervision links with the graph revision. ${WS_SCOPES}`,
+    properties: { workspace: WORKSPACE }, required: ["workspace"], readOnly: true,
+    run: async (hub, args, signal) => {
+      const id = need(args, "workspace")
+      const [{ workspace, bindings }, { members }, graph] = await Promise.all([hub.workspaces.get(id, { signal }), hub.workspaces.members(id, { signal }), hub.workspaces.supervision(id, { signal })])
+      const lines = [wsLine(workspace)]
+      if (workspace.masterMemberID) lines.push(`master: ${workspace.masterMemberID}`)
+      if (bindings.length) lines.push("bindings:", ...bindings.map((b) => `  ${b.id}  ${b.machineID}:${b.repo}  r${b.revision}`))
+      lines.push(members.length ? "members:" : "no current members", ...members.map((m) => `  ${m.member.id}  ${m.member.sessionID}  ${m.member.role}  ${m.presence}  r${m.member.revision}`))
+      lines.push(`supervision revision ${graph.revision}`, ...graph.links.map((l) => `  ${l.link.memberID} ← ${l.link.supervisorMemberID}  order ${l.link.order}${l.member !== "current" || l.supervisor !== "current" ? "  (stale)" : ""}`))
+      return lines.join("\n")
+    },
+  },
+  {
+    name: "workspace_create",
+    description: `Create a coordination workspace. ${WS_SCOPES}`,
+    properties: { title: STRING, description: STRING, tags: { type: "array", items: STRING }, idempotencyKey: IDEMPOTENCY }, required: ["title"], readOnly: false,
+    run: async (hub, args, signal) => {
+      const description = optional(args, "description")
+      const tags = optionalStrings(args, "tags")
+      const { workspace } = await hub.workspaces.create({ title: need(args, "title"), ...(description ? { description } : {}), ...(tags ? { tags } : {}) }, { ...idemOption(args), signal })
+      return `created ${wsLine(workspace)}`
+    },
+  },
+  {
+    name: "workspace_update",
+    description: `Change a workspace's title, description or tags under its revision. ${WS_SCOPES}`,
+    properties: { workspace: WORKSPACE, expectedRevision: REVISION, title: STRING, description: STRING, tags: { type: "array", items: STRING } }, required: ["workspace", "expectedRevision"], readOnly: false,
+    run: async (hub, args, signal) => {
+      const patch = definedFields({ title: optional(args, "title"), description: optional(args, "description"), tags: optionalStrings(args, "tags") })
+      if (!patch) throw new ArgError(`give "title", "description" or "tags"`)
+      const { workspace } = await hub.workspaces.update(need(args, "workspace"), { expectedRevision: needRevision(args), ...patch }, { signal })
+      return `updated ${wsLine(workspace)}`
+    },
+  },
+  ...(["archive", "restore"] as const).map((verb): Tool => ({
+    name: `workspace_${verb}`,
+    description: verb === "archive" ? `Archive a workspace under its revision: current members depart and their supervision links are detached. ${WS_SCOPES}` : `Restore an archived workspace under its revision (nobody re-joins). ${WS_SCOPES}`,
+    properties: { workspace: WORKSPACE, expectedRevision: REVISION }, required: ["workspace", "expectedRevision"], readOnly: false, idempotent: true,
+    run: async (hub, args, signal) => {
+      const id = need(args, "workspace")
+      if (verb === "archive") {
+        const r = await hub.workspaces.archive(id, needRevision(args), { signal })
+        return `archived ${wsLine(r.workspace)}; ${r.departed} member(s) departed, ${r.supervision.detached} supervision link(s) detached`
+      }
+      return `restored ${wsLine((await hub.workspaces.restore(id, needRevision(args), { signal })).workspace)}`
+    },
+  })),
+  {
+    name: "workspace_bind",
+    description: `Bind a workspace to a repository (absolute path) on one of the user's machines. ${WS_SCOPES}`,
+    properties: { workspace: WORKSPACE, machineID: STRING, repo: STRING, label: STRING, idempotencyKey: IDEMPOTENCY }, required: ["workspace", "machineID", "repo"], readOnly: false, idempotent: true,
+    run: async (hub, args, signal) => {
+      const label = optional(args, "label")
+      const r = await hub.workspaces.bind(need(args, "workspace"), { machineID: need(args, "machineID"), repo: need(args, "repo"), ...(label ? { label } : {}) }, { ...idemOption(args), signal })
+      return `${r.created ? "bound" : "already bound"} ${r.binding.id}  ${r.binding.machineID}:${r.binding.repo}  r${r.binding.revision}`
+    },
+  },
+  {
+    name: "workspace_unbind",
+    description: `Remove a repository binding under the binding's revision. ${WS_SCOPES}`,
+    properties: { workspace: WORKSPACE, bindingID: STRING, expectedRevision: REVISION }, required: ["workspace", "bindingID", "expectedRevision"], readOnly: false,
+    run: async (hub, args, signal) => {
+      await hub.workspaces.unbind(need(args, "workspace"), need(args, "bindingID"), needRevision(args), { signal })
+      return `unbound ${need(args, "bindingID")}`
+    },
+  },
+  {
+    name: "workspace_join",
+    description: `Add a session (ses_…) to a workspace as worker or observer (the master is set by explicit replacement). ${WS_SCOPES}`,
+    properties: { workspace: WORKSPACE, sessionID: STRING, role: { type: "string", enum: [...MEMBER_ROLES] }, idempotencyKey: IDEMPOTENCY }, required: ["workspace", "sessionID", "role"], readOnly: false, idempotent: true,
+    run: async (hub, args, signal) => {
+      const role = optionalEnum(args, "role", MEMBER_ROLES)
+      if (!role) throw new ArgError(`"role" is one of ${MEMBER_ROLES.join(", ")}`)
+      const { member, created } = await hub.workspaces.join(need(args, "workspace"), { sessionID: need(args, "sessionID"), role }, { ...idemOption(args), signal })
+      return `member ${member.id} (${member.sessionID}, ${member.role}, generation ${member.generation}, r${member.revision}) ${created ? "joined" : "was already a member"}`
+    },
+  },
+  {
+    name: "workspace_leave",
+    description: `Remove a member under its revision; its supervision links are detached. ${WS_SCOPES}`,
+    properties: { workspace: WORKSPACE, memberID: STRING, expectedRevision: REVISION }, required: ["workspace", "memberID", "expectedRevision"], readOnly: false, idempotent: true,
+    run: async (hub, args, signal) => {
+      const r = await hub.workspaces.leave(need(args, "workspace"), need(args, "memberID"), needRevision(args), { signal })
+      return `member ${r.member.id} left (${r.member.leftReason ?? "removed"}); ${r.supervision.detached} supervision link(s) detached`
+    },
+  },
+  {
+    name: "workspace_assign",
+    description: `Give a current member an assignment (title and optional outcome criteria; instructions travel as messages). ${WS_SCOPES}`,
+    properties: { workspace: WORKSPACE, memberID: STRING, title: STRING, criteria: { type: "array", items: STRING }, ref: STRING, idempotencyKey: IDEMPOTENCY }, required: ["workspace", "memberID", "title"], readOnly: false,
+    run: async (hub, args, signal) => {
+      const criteria = optionalStrings(args, "criteria")
+      const ref = optional(args, "ref")
+      const { assignment } = await hub.workspaces.assign(need(args, "workspace"), { memberID: need(args, "memberID"), title: need(args, "title"), ...(criteria ? { criteria } : {}), ...(ref ? { ref } : {}) }, { ...idemOption(args), signal })
+      return `assignment ${assignment.id} → ${assignment.memberID}: ${assignment.status}, r${assignment.revision}`
+    },
+  },
+  {
+    name: "workspace_assignments",
+    description: `A workspace's assignments (id, member, status, revision, title), optionally one member's or one status. ${WS_SCOPES}`,
+    properties: { workspace: WORKSPACE, memberID: STRING, status: { type: "string", enum: [...ASSIGNMENT_STATUSES] } }, required: ["workspace"], readOnly: true,
+    run: async (hub, args, signal) => {
+      const memberID = optional(args, "memberID")
+      const status = optionalEnum(args, "status", ASSIGNMENT_STATUSES)
+      const r = await hub.workspaces.assignments(need(args, "workspace"), { ...(memberID ? { memberID } : {}), ...(status ? { status } : {}), limit: 200, signal })
+      return r.items.length ? r.items.map((v) => `${v.assignment.id}  ${v.assignment.memberID} (${v.member}, ${v.presence})  ${v.assignment.status}  r${v.assignment.revision}  ${oneLine(sanitizeText(v.assignment.title))}`).join("\n") : "no assignments"
+    },
+  },
+  {
+    name: "workspace_assignment_update",
+    description: `Set an assignment's status (done and cancelled are final) or move it to another current member, under its revision. ${WS_SCOPES}`,
+    properties: { workspace: WORKSPACE, assignmentID: STRING, expectedRevision: REVISION, status: { type: "string", enum: [...ASSIGNMENT_STATUSES] }, memberID: STRING }, required: ["workspace", "assignmentID", "expectedRevision"], readOnly: false,
+    run: async (hub, args, signal) => {
+      const status = optionalEnum(args, "status", ASSIGNMENT_STATUSES)
+      const memberID = optional(args, "memberID")
+      if ((status === undefined) === (memberID === undefined)) throw new ArgError(`give exactly one of "status" or "memberID"`)
+      const id = need(args, "workspace")
+      const assignmentID = need(args, "assignmentID")
+      const { assignment } = status !== undefined
+        ? await hub.workspaces.setAssignmentStatus(id, assignmentID, status, needRevision(args), { signal })
+        : await hub.workspaces.reassign(id, assignmentID, memberID!, needRevision(args), { signal })
+      return `assignment ${assignment.id} → ${assignment.memberID}: ${assignment.status}, r${assignment.revision}`
+    },
+  },
+  {
+    name: "workspace_supervise",
+    description: `Set who supervises a member (supervisor null detaches), under the supervision graph's revision (workspace_show). Acyclic, at most 6 levels. ${WS_SCOPES}`,
+    properties: { workspace: WORKSPACE, memberID: STRING, supervisor: { type: ["string", "null"], description: "The supervising member's ID, or null to detach." }, order: { type: "number" }, expectedRevision: REVISION }, required: ["workspace", "memberID", "supervisor", "expectedRevision"], readOnly: false,
+    run: async (hub, args, signal) => {
+      const supervisor = args.supervisor === null ? null : need(args, "supervisor")
+      const order = args.order
+      if (order !== undefined && (typeof order !== "number" || !Number.isFinite(order))) throw new ArgError(`"order" must be a number`)
+      const r = await hub.workspaces.supervise(need(args, "workspace"), { memberID: need(args, "memberID"), supervisorMemberID: supervisor, ...(order !== undefined ? { order } : {}), expectedRevision: needRevision(args) }, { signal })
+      return `${r.change}: ${need(args, "memberID")}${r.link ? ` ← ${r.link.supervisorMemberID} (order ${r.link.order})` : ""}; supervision revision ${r.revision}${r.pruned ? `, ${r.pruned} stale link(s) dropped` : ""}`
+    },
+  },
+  {
+    name: "workspace_master",
+    description: `A workspace's master: the current master member (session, generation, presence), earlier masters and a replacement in flight. ${WS_SCOPES}`,
+    properties: { workspace: WORKSPACE }, required: ["workspace"], readOnly: true,
+    run: async (hub, args, signal) => {
+      const v = await hub.workspaces.master(need(args, "workspace"), { signal })
+      const line = (m: { member: { id: string; sessionID: string; generation: number; leftReason?: string }; presence: string }) => `${m.member.id}  ${m.member.sessionID}  generation ${m.member.generation}  ${m.presence}${m.member.leftReason ? `  (${m.member.leftReason})` : ""}`
+      return [
+        `workspace ${v.workspaceID} r${v.revision}`,
+        v.master ? `master: ${line(v.master)}` : "no master",
+        ...(v.pending ? [`replacement in flight: ${v.pending.phase}${v.pending.stale ? " (stale)" : ""}`] : []),
+        ...(v.previous.length ? ["earlier masters:", ...v.previous.map((p) => `  ${line(p)}`)] : []),
+      ].join("\n")
+    },
+  },
+  {
+    name: "workspace_master_replace",
+    description: `Replace (or first set) a workspace's master under the workspace revision: a session (ses_…) or a running launch's session (launchID). The old master departs as replaced; its supervised members move to the new one. No grants move: the new master's session needs its own grants. ${WS_SCOPES}`,
+    properties: { workspace: WORKSPACE, sessionID: STRING, launchID: STRING, expectedRevision: REVISION, idempotencyKey: IDEMPOTENCY }, required: ["workspace", "expectedRevision"], readOnly: false, idempotent: true,
+    run: async (hub, args, signal) => {
+      const sessionID = optional(args, "sessionID")
+      const launchID = optional(args, "launchID")
+      if ((sessionID === undefined) === (launchID === undefined)) throw new ArgError(`give exactly one of "sessionID" or "launchID"`)
+      const target = sessionID !== undefined ? { sessionID } : { launchID: launchID! }
+      const r = await hub.workspaces.replaceMaster(need(args, "workspace"), { ...target, expectedRevision: needRevision(args) }, { ...idemOption(args), signal })
+      if (!r.changed) return `${r.master.sessionID} already is the master (${r.master.id}); nothing changed`
+      return [
+        `master ${r.master.id} (${r.master.sessionID}, generation ${r.master.generation}, ${r.presence}); workspace r${r.workspace.revision}`,
+        ...(r.previous ? [`replaced ${r.previous.id} (${r.previous.sessionID}); ${r.supervision?.transferred ?? 0} supervision link(s) moved, ${r.supervision?.detached ?? 0} detached`] : []),
+        r.grants.note,
+      ].join("\n")
+    },
+  },
+  {
+    name: "workspace_board",
+    description: `The workspace's situation board: members with presence, session state and blocker references, supervision, assignments with their explicit status, open Decisions concerning members and artifact references, with stale markers. Bounded and read-only; details (blocker summaries, Decision questions, criteria) stay behind show, decision_show and workspace_assignments. ${WS_SCOPES} The board needs sessions:read; Decisions need messages:read and artifacts artifacts:read, else they are omitted.`,
+    properties: { workspace: WORKSPACE }, required: ["workspace"], readOnly: true,
+    run: async (hub, args, signal) => {
+      const b = await hub.workspaces.board(need(args, "workspace"), { signal })
+      const more = (truncated: boolean) => (truncated ? "  (more not shown)" : "")
+      type Section<T> = { status: "ok"; items: readonly T[]; truncated: boolean } | { status: "omitted"; scope: string } | { status: "unsupported" | "failed" }
+      const section = <T,>(name: string, s: Section<T>, line: (item: T) => string): string[] =>
+        s.status === "ok" ? [`${name}:${more(s.truncated)}`, ...s.items.map((i) => `  ${line(i)}`)] : [`${name}: ${s.status}${s.status === "omitted" ? ` (needs ${s.scope})` : ""}`]
+      const lines = [wsLine(b.workspace), ...(b.workspace.masterMemberID ? [`master: ${b.workspace.masterMemberID}`] : [])]
+      lines.push(`members (${b.members.total}):${more(b.members.truncated)}`, ...b.members.items.map((m) => `  ${m.memberID}  ${m.sessionID}  ${m.role}  ${m.presence}  ${m.session?.state ?? "?"}  blockers ${m.blockers.reported ? m.blockers.count : "not reported"}${m.stale ? `  (stale: ${m.stale})` : ""}`))
+      lines.push(`supervision revision ${b.supervision.revision}`, ...b.supervision.links.map((l) => `  ${l.memberID} ← ${l.supervisorMemberID}  order ${l.order}`))
+      lines.push(`assignments:${more(b.assignments.truncated)}`, ...b.assignments.items.map((a) => `  ${a.id}  ${a.memberID}  ${a.status}  r${a.revision}  ${oneLine(sanitizeText(a.title))}${a.stale ? `  (stale: ${a.stale.join(", ")})` : ""}`))
+      lines.push(...section("decisions", b.decisions, (d) => `${d.id}  ${d.urgency}  ${d.memberIDs.join(",")}${d.stale ? `  (${d.stale})` : ""}`))
+      lines.push(...section("artifacts", b.artifacts, (a) => `${a.id}  ${a.kind}  ${a.latestRevisionID}  r${a.revision}`))
+      return lines.join("\n")
+    },
+  },
+]
+
 const TOOLS: readonly Tool[] = [
   ...archiveTools(true),
   ...archiveTools(false),
   ...pinTools(true),
   ...pinTools(false),
   archiveInactiveTool,
+  ...intentTools,
   ...nameTools,
   eventsTool,
   ...webhookTools,
+  ...profileTools,
+  ...profileLifecycleTools,
+  ...workspaceTools,
+  ...artifactTools,
+  ...artifactJobTools,
+  ...teamIntakeTools,
+  ...teamTools,
+  ...watchlistTools,
   {
     name: "whoami",
     description: "Who this hub credential is: the app token of `hub login` (or the session of HUB_SESSION_TOKEN) and its user.",
@@ -426,10 +793,17 @@ const TOOLS: readonly Tool[] = [
   },
   {
     name: "who",
-    description: "Named and role-holding sessions.",
-    properties: { project: { ...STRING, description: "Only this project." }, role: { ...STRING, description: "Only holders of this role (reviewer or @@reviewer)." } },
+    description: "Named and role-holding sessions; a team member sees its teams, grouped by team with its reach to each.",
+    properties: {
+      project: { ...STRING, description: "Only this project." },
+      role: { ...STRING, description: "Only holders of this role (reviewer, @@reviewer or reviewer#team)." },
+      team: { ...STRING, description: "Only this team (name or ID)." },
+    },
     readOnly: true,
-    run: async (hub, args, signal) => whoText((await hub.who({ project: optional(args, "project"), role: optional(args, "role"), signal })).sessions ?? []),
+    run: async (hub, args, signal) => {
+      const body = await hub.who({ project: optional(args, "project"), role: optional(args, "role"), team: optional(args, "team"), signal })
+      return whoText(body.sessions ?? [], body)
+    },
   },
   {
     name: "msg",
@@ -710,6 +1084,7 @@ function errorText(error: CliError): string {
   if (typeof envelope?.feature === "string") lines.push(`missing feature: ${envelope.feature}${typeof envelope.harness === "string" ? ` (${envelope.harness})` : ""}`)
   if (envelope?.code === "needs_user") lines.push(...needsUserLines(envelope))
   if (typeof envelope?.retryAfter === "number") lines.push(`retry after ${Math.ceil(envelope.retryAfter)} s`)
+  if (typeof envelope?.currentRevision === "number") lines.push(`current revision ${envelope.currentRevision}`)
   if (error.hint) lines.push(`hint: ${error.hint}`)
   return lines.join("\n")
 }
@@ -768,7 +1143,7 @@ export function createMcpServer(options: McpServerOptions): McpServer {
       return controller.signal.aborted ? undefined : ok(id, toolResult(clean(text, token), false))
     } catch (cause) {
       if (controller.signal.aborted) return undefined // cancelled: no answer (MCP cancellation)
-      const text = cause instanceof ArgError ? `invalid: ${cause.message}` : cause instanceof CliError ? errorText(cause) : `${tool.name} failed: ${cause instanceof Error ? cause.message : String(cause)}`
+      const text = cause instanceof ArgError || cause instanceof ProfileArgError ? `invalid: ${cause.message}` : cause instanceof CliError ? errorText(cause) : `${tool.name} failed: ${cause instanceof Error ? cause.message : String(cause)}`
       return ok(id, toolResult(clean(text, token), true))
     } finally {
       if (inFlight.get(key(id)) === controller) inFlight.delete(key(id))

package/packages/cli/src/messaging.ts

@@ -1,6 +1,7 @@
 // The messaging verbs' helpers (design §3): text arguments (or "-" for stdin) and the short text of what the hub
 // answers to msg, ask, reply, decline, inbox and mute. The shapes are packages/sdk's types (message-routes.ts).
 import type { AgentMessage, Asked, Inbox, MessageDelivery, Party, Replied, Sent } from "../../sdk/src/index.ts"
+import { wakeSkipNote } from "../../sdk/src/wake.ts"
 import { UsageError } from "./args"
 import { oneLine } from "./format"
 
@@ -27,7 +28,10 @@ const DELIVERY: Record<MessageDelivery, string> = {
   steer: "delivered (into the running turn)",
   queued: "queued (read at its next turn)",
   retained: "retained (held until its open question is answered)",
-  pending: "pending (offline; delivered when it reconnects, for 24 h)",
+  // Offline recipients, and a --no-wake message to a busy OpenCode session (RF-05); the hub's answer does not say which.
+  pending: "pending (offline or busy; delivered when it reconnects or its turn ends, for 24 h)",
+  dropped: "not delivered (its recipient session ended)",
+  expired: "not delivered (its recipient stayed offline or busy for 24 h)",
 }
 
 export const deliveryText = (delivery: MessageDelivery | undefined): string => (delivery ? (DELIVERY[delivery] ?? delivery) : "stored (in its inbox)")
@@ -38,8 +42,8 @@ function toText(message: AgentMessage): string {
   return message.to === recipient || message.to === (message.recipient as { sessionID?: string }).sessionID ? recipient : `${message.to} → ${recipient}`
 }
 
-/** `msg_… to @web-work: delivered (started a turn)` */
-export const sentText = ({ message, delivery }: Sent): string => `${message.kind} ${message.id} to ${toText(message)}: ${deliveryText(delivery)}`
+/** `msg_… to @web-work: delivered (started a turn)`; `…: queued (read at its next turn) — wake skipped: …` */
+export const sentText = (sent: Sent): string => `${sent.message.kind} ${sent.message.id} to ${toText(sent.message)}: ${deliveryText(sent.delivery)}${wakeSkipNote(sent)}`
 
 /** How long an ask stays open when --expires is not given (the hub's default). */
 export const ASK_EXPIRES_DEFAULT_S = 24 * 60 * 60