@huynle/hub 0.7.4 → 0.8.1

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

@@ -0,0 +1,301 @@
+// MCP tools for the profile lifecycle (FX-03, m8sthu85): show a profile and its versions, create one, edit its
+// metadata, write new versions (whole content, a rollback, or one skill or command attached/detached), archive and
+// restore it, and pin a version to a session. The read tools a session uses on its own pin (profile, profile_skill,
+// profile_command) and the listing (profiles, profile_usage) stay in mcp.ts.
+//
+// Profiles are immutable versioned bundles (HWA-14, RP-08): nothing here edits a version. Every content change is
+// POST /profiles/:id/versions with the profile's revision; attaching or detaching a skill or command reads the latest
+// version and writes its content with that one change as the next version (a stale revision answers conflict, so a
+// concurrent change is never overwritten). No server behaviour is added: each tool is one existing route of
+// src/central/profiles/routes.ts (plus the reads it needs).
+//
+// Annotations for gateway review (packages/cli/src/mcp.ts maps them): reads are readOnlyHint; create, metadata edits
+// and new versions only reorganize (destructiveHint false: pinned sessions keep their explicit version, and an old
+// version can be restored with fromVersion); archive/restore (no new versions or pins) and pins (applied to a running
+// session) keep the default destructiveHint. Changes send expectedRevision, so repeating one is idempotent.
+import { sanitizeText } from "../../sdk/src/envelope.ts"
+import type { Profiles } from "../../sdk/src/client.ts"
+import type { ProfileCommand, ProfileContent, ProfileSkill, ProfileVersionSummary, ProfileView } from "../../sdk/src/types.ts"
+
+type Args = Record<string, unknown>
+
+/** The shape of an MCP tool (as packages/cli/src/mcp.ts registers them). */
+export interface ProfileTool {
+  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 profiles: Profiles }, args: Args, signal: AbortSignal): Promise<string>
+}
+
+const STRING = { type: "string" } as const
+const STRINGS = { type: "array", items: STRING } as const
+const ID = { type: "string", description: "The profile's ID (prof_…; see profiles)." } as const
+const REVISION = { type: "integer", minimum: 0, description: "The profile's revision you read (profile_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 SKILL = { type: "object", properties: { name: { ...STRING, description: "A slug." }, description: STRING, body: { ...STRING, description: "The skill's full text (loaded on demand)." } }, required: ["name", "description", "body"] } as const
+const COMMAND = { type: "object", properties: { name: { ...STRING, description: "A slug." }, description: STRING, template: { ...STRING, description: "Text with {{name}} parameters and {{secret:NAME}} references (never resolved by the hub)." } }, required: ["name", "description", "template"] } as const
+const CONTENT_FIELDS = {
+  instructions: { type: ["string", "null"], description: "The profile's instructions (AGENTS.md-like text)." },
+  model: { type: ["string", "null"], description: "provider/model the profile suggests." },
+  skills: { type: "array", items: SKILL, description: "Skills, wholesale." },
+  commands: { type: "array", items: COMMAND, description: "Commands, wholesale." },
+} as const
+const META_FIELDS = {
+  title: { ...STRING, description: "1–120 characters." },
+  description: STRING,
+  tags: { ...STRINGS, description: "Slugs." },
+  metadata: { type: "object", additionalProperties: STRING, description: "String key/value pairs (≤ 32 slug keys)." },
+  projects: { ...STRINGS, description: "Project names the profile is meant for (≤ 16)." },
+} as const
+const SCOPES = "App tokens need scope profiles:read (reads) or profiles:manage (changes; profile_version_create with content fields and the skill/command set/remove tools read the latest version first, so they also need profiles:read); pins need profiles:assign and sessions:read (an app also needs a prompt grant on the session). Session tokens never change profiles. A profile confers no authority."
+
+/** A bad tool argument: mcp.ts answers it as `invalid: …` (an isError result). */
+export class ProfileArgError extends Error {}
+const ArgError = ProfileArgError
+
+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 whole = (args: Args, key: string, min: number, what: string): number => {
+  const value = args[key]
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < min) throw new ArgError(`"${key}" is required: ${what}`)
+  return value
+}
+const revision = (args: Args): number => whole(args, "expectedRevision", 0, "the revision you read (profile_show; 0 for a session with no pin)")
+const idempotency = (args: Args) => {
+  const key = optional(args, "idempotencyKey")
+  return key ? { idempotencyKey: key } : {}
+}
+/** 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, " ")
+
+/** `prof_…  name  vN rN  state  title` */
+export const profileLine = (p: ProfileView): string => `${p.id}  ${p.name}  v${p.latestVersion} r${p.revision}  ${p.state}  ${one(p.title)}`
+
+/** A version's contents by name (never bodies). */
+function summaryLines(v: ProfileVersionSummary | undefined): string[] {
+  if (!v) return []
+  return [
+    `version ${v.version} (${v.digest.slice(0, 12)}, ${v.bytes} bytes): instructions ${v.instructions ? "yes" : "no"}${v.model ? `, model ${one(v.model)}` : ""}`,
+    `skills: ${v.skills.length ? v.skills.map((s) => s.name).join(", ") : "none"}`,
+    `commands: ${v.commands.length ? v.commands.map((c) => `${c.name}(${c.params.join(", ")})`).join(", ") : "none"}`,
+    ...(v.secretRefs.length ? [`secret references: ${v.secretRefs.join(", ")}`] : []),
+  ]
+}
+
+const versionText = (r: { profile: ProfileView; version: ProfileVersionSummary }) => [`new version ${r.version.version}: ${profileLine(r.profile)}`, ...summaryLines(r.version)].join("\n")
+
+/** The content of a profile's latest version (what an attach/detach starts from). */
+async function latestContent(profiles: Profiles, id: string, signal: AbortSignal): Promise<{ latest: number; content: ProfileContent }> {
+  const { profile } = await profiles.get(id, { signal })
+  const { version } = await profiles.version(profile.id, profile.latestVersion, { signal })
+  return { latest: version.version, content: version.content }
+}
+
+/** A tool writing the latest version's content with one change as the next version. */
+const contentTool = (
+  name: string,
+  description: string,
+  properties: Record<string, unknown>,
+  required: readonly string[],
+  change: (content: ProfileContent, args: Args, latest: number) => ProfileContent,
+): ProfileTool => ({
+  name,
+  description: `${description} Writes the latest version's content with this change as the next version (versions are immutable; pinned sessions keep theirs). ${SCOPES}`,
+  properties: { id: ID, ...properties, expectedRevision: REVISION },
+  required: ["id", ...required, "expectedRevision"],
+  readOnly: false,
+  organizes: true,
+  idempotent: true,
+  run: async (hub, args, signal) => {
+    const expectedRevision = revision(args)
+    const id = need(args, "id")
+    const { latest, content } = await latestContent(hub.profiles, id, signal)
+    return versionText(await hub.profiles.createVersion(id, { expectedRevision, content: change(content, args, latest) }, { signal }))
+  },
+})
+
+/** `items` with `item` replacing the one of its name (in place), else appended. */
+const setNamed = <T extends { readonly name: string }>(items: readonly T[], item: T): T[] =>
+  items.some((i) => i.name === item.name) ? items.map((i) => (i.name === item.name ? item : i)) : [...items, item]
+const removeNamed = <T extends { readonly name: string }>(items: readonly T[], name: string, what: string, latest: number): T[] => {
+  if (!items.some((i) => i.name === name)) throw new ArgError(`version ${latest} has no ${what} ${name}`)
+  return items.filter((i) => i.name !== name)
+}
+
+const stateTool = (verb: "archive" | "restore", description: string): ProfileTool => ({
+  name: `profile_${verb}`,
+  description: `${description} ${SCOPES}`,
+  properties: { id: ID, expectedRevision: REVISION },
+  required: ["id", "expectedRevision"],
+  readOnly: false,
+  idempotent: true,
+  run: async (hub, args, signal) => {
+    const expectedRevision = revision(args)
+    const { profile } = await hub.profiles.update(need(args, "id"), { expectedRevision, state: verb === "archive" ? "archived" : "active" }, { signal })
+    return `${verb === "archive" ? "archived" : "restored"}: ${profileLine(profile)}`
+  },
+})
+
+export const profileLifecycleTools: readonly ProfileTool[] = [
+  // ---------- reads ----------
+  {
+    name: "profile_show",
+    description: `One profile: name, title, state, revision (send it as expectedRevision), tags, projects, metadata, and its latest version's instructions, model, skill and command names (never bodies). ${SCOPES}`,
+    properties: { id: ID },
+    required: ["id"],
+    readOnly: true,
+    run: async (hub, args, signal) => {
+      const { profile, latest } = await hub.profiles.get(need(args, "id"), { signal })
+      return [
+        profileLine(profile),
+        ...(profile.description ? [`description: ${one(profile.description)}`] : []),
+        ...(profile.tags?.length ? [`tags: ${profile.tags.join(", ")}`] : []),
+        ...(profile.projects?.length ? [`projects: ${profile.projects.map(one).join(", ")}`] : []),
+        ...(profile.metadata && Object.keys(profile.metadata).length ? [`metadata: ${Object.entries(profile.metadata).map(([k, v]) => `${k}=${one(v)}`).join(", ")}`] : []),
+        ...summaryLines(latest),
+      ].join("\n")
+    },
+  },
+  {
+    name: "profile_versions",
+    description: `A profile's retained versions, newest first (version, digest, bytes, when, skill and command counts). ${SCOPES}`,
+    properties: { id: ID, limit: { type: "integer", minimum: 1, maximum: 200 }, cursor: STRING },
+    required: ["id"],
+    readOnly: true,
+    run: async (hub, args, signal) => {
+      const limit = args.limit === undefined ? undefined : whole(args, "limit", 1, "a whole number from 1 to 200")
+      const cursor = optional(args, "cursor")
+      const page = await hub.profiles.versions(need(args, "id"), { signal, ...(limit !== undefined ? { limit } : {}), ...(cursor ? { cursor } : {}) })
+      const counts = (v: (typeof page.items)[number]) => (v.skills !== undefined ? `  ${v.skills} skills, ${v.commands ?? 0} commands${v.instructions ? ", instructions" : ""}` : "")
+      return [...page.items.map((v) => `v${v.version}  ${v.digest.slice(0, 12)}  ${v.bytes} bytes  ${new Date(v.createdAt).toISOString()}${counts(v)}`), ...(page.cursor ? [`more: cursor ${page.cursor}`] : [])].join("\n") || "no versions"
+    },
+  },
+
+  // ---------- definitions ----------
+  {
+    name: "profile_create",
+    description: `Create a profile: a versioned bundle of instructions, skills and commands, published as version 1 at once. The name is unique per user. Attach it to a team role with team_role_set (profile), pin it with profile_assign. ${SCOPES}`,
+    properties: { name: { ...STRING, description: "A slug, unique per user." }, ...META_FIELDS, ...CONTENT_FIELDS, idempotencyKey: IDEMPOTENCY },
+    required: ["name", "title"],
+    readOnly: false,
+    organizes: true,
+    idempotent: true,
+    run: async (hub, args, signal) => {
+      need(args, "name")
+      need(args, "title")
+      const meta = picked(args, ["name", "title", "description", "tags", "metadata", "projects"]) as { name: string; title: string }
+      const text = Object.entries(picked(args, ["instructions", "model"])).filter(([, v]) => v !== null)
+      const content = { ...Object.fromEntries(text), skills: (args.skills ?? []) as ProfileSkill[], commands: (args.commands ?? []) as ProfileCommand[] } as ProfileContent
+      const r = await hub.profiles.create({ ...meta, content }, { signal, ...idempotency(args) })
+      // A replay of the same idempotencyKey answers the first result again (the API does not mark replays).
+      return [`created: ${profileLine(r.profile)}`, ...summaryLines(r.version)].join("\n")
+    },
+  },
+  {
+    name: "profile_update",
+    description: `Edit a profile's metadata: title, description, tags, metadata, projects (null clears description, metadata or projects). Content changes are new versions (profile_version_create, profile_skill_set, …). ${SCOPES}`,
+    properties: { id: ID, ...META_FIELDS, description: { type: ["string", "null"] }, metadata: { ...META_FIELDS.metadata, type: ["object", "null"] }, projects: { ...META_FIELDS.projects, type: ["array", "null"] }, expectedRevision: REVISION },
+    required: ["id", "expectedRevision"],
+    readOnly: false,
+    organizes: true,
+    idempotent: true,
+    run: async (hub, args, signal) => {
+      const expectedRevision = revision(args)
+      const patch = picked(args, ["title", "description", "tags", "metadata", "projects"])
+      if (Object.keys(patch).length === 0) throw new ArgError("give at least one field to change")
+      const { profile } = await hub.profiles.update(need(args, "id"), { expectedRevision, ...patch }, { signal })
+      return `updated: ${profileLine(profile)}`
+    },
+  },
+  {
+    name: "profile_version_create",
+    description: `Write a profile's next version: either content fields (instructions, model, skills, commands; the ones you omit are kept from the latest version, null clears instructions or model) or fromVersion (an older version's content again: an explicit rollback). Versions are immutable; pinned sessions keep theirs until re-pinned. ${SCOPES}`,
+    properties: { id: ID, ...CONTENT_FIELDS, fromVersion: { type: "integer", minimum: 1, description: "A retained version to restore as the next one." }, expectedRevision: REVISION, idempotencyKey: IDEMPOTENCY },
+    required: ["id", "expectedRevision"],
+    readOnly: false,
+    organizes: true,
+    idempotent: true,
+    run: async (hub, args, signal) => {
+      const expectedRevision = revision(args)
+      const id = need(args, "id")
+      const given = Object.keys(picked(args, Object.keys(CONTENT_FIELDS)))
+      const options = { signal, ...idempotency(args) }
+      if (args.fromVersion !== undefined) {
+        if (given.length) throw new ArgError(`give either fromVersion or content fields (${given.join(", ")}), not both`)
+        return versionText(await hub.profiles.createVersion(id, { expectedRevision, fromVersion: whole(args, "fromVersion", 1, "a version number") }, options))
+      }
+      if (!given.length) throw new ArgError("give content fields (instructions, model, skills, commands) or fromVersion")
+      const { content } = await latestContent(hub.profiles, id, signal)
+      const next: Record<string, unknown> = { ...content }
+      for (const key of given) {
+        if (args[key] === null) delete next[key]
+        else next[key] = args[key]
+      }
+      return versionText(await hub.profiles.createVersion(id, { expectedRevision, content: next as unknown as ProfileContent }, options))
+    },
+  },
+  contentTool("profile_skill_set", "Attach a skill to a profile, or replace the skill of that name.", { name: { ...STRING, description: "The skill's name (a slug)." }, description: STRING, body: { ...STRING, description: "The skill's full text." } }, ["name", "description", "body"], (content, args) => ({
+    ...content,
+    skills: setNamed(content.skills, { name: need(args, "name"), description: need(args, "description"), body: need(args, "body") }),
+  })),
+  contentTool("profile_skill_remove", "Detach a skill from a profile.", { name: { ...STRING, description: "The skill's name." } }, ["name"], (content, args, latest) => ({
+    ...content,
+    skills: removeNamed(content.skills, need(args, "name"), "skill", latest),
+  })),
+  contentTool(
+    "profile_command_set",
+    "Attach a command to a profile, or replace the command of that name.",
+    { name: { ...STRING, description: "The command's name (a slug)." }, description: STRING, template: COMMAND.properties.template },
+    ["name", "description", "template"],
+    (content, args) => ({ ...content, commands: setNamed(content.commands, { name: need(args, "name"), description: need(args, "description"), template: need(args, "template") }) }),
+  ),
+  contentTool("profile_command_remove", "Detach a command from a profile.", { name: { ...STRING, description: "The command's name." } }, ["name"], (content, args, latest) => ({
+    ...content,
+    commands: removeNamed(content.commands, need(args, "name"), "command", latest),
+  })),
+  stateTool("archive", "Archive a profile: it takes no new versions or pins; pinned sessions keep theirs; reversible with profile_restore."),
+  stateTool("restore", "Restore an archived profile (it takes versions and pins again)."),
+
+  // ---------- pins ----------
+  {
+    name: "profile_assign",
+    description: `Pin a profile version to a session (applied through its machine; the ack tells whether it took). Send the session's pin revision (0 when it has none; see profile). Pinning confers no authority. ${SCOPES}`,
+    properties: { addr: { ...STRING, description: "The session: @name, ses_… ID or other address." }, profileID: ID, version: { type: "integer", minimum: 1 }, expectedRevision: { ...REVISION, description: "The session's pin revision (0 when it has none)." } },
+    required: ["addr", "profileID", "version", "expectedRevision"],
+    readOnly: false,
+    idempotent: true,
+    run: async (hub, args, signal) => {
+      const expectedRevision = revision(args)
+      const { assignment: a } = await hub.profiles.assign(need(args, "addr"), { profileID: need(args, "profileID"), version: whole(args, "version", 1, "a version number"), expectedRevision }, { signal })
+      return `${a.sessionID} pins ${a.profileID} v${a.version} r${a.revision}${a.ack ? `, ack ${a.ack.status}${a.ack.offline ? " (offline)" : ""}` : ""}`
+    },
+  },
+  {
+    name: "profile_unassign",
+    description: `Remove a session's pin (what it already applied stays until it restarts). Send the pin's revision (profile_assign's answer). ${SCOPES}`,
+    properties: { addr: { ...STRING, description: "The session." }, expectedRevision: { ...REVISION, description: "The session's pin revision." } },
+    required: ["addr", "expectedRevision"],
+    readOnly: false,
+    idempotent: true,
+    run: async (hub, args, signal) => {
+      const addr = need(args, "addr")
+      await hub.profiles.unassign(addr, revision(args), { signal })
+      return `unpinned ${addr}`
+    },
+  },
+]

package/packages/cli/src/setup/commands.ts

@@ -56,7 +56,8 @@ import { TxStore } from "../bootstrap/transaction/store.ts"
 import type { TxOutcome } from "../bootstrap/transaction/engine.ts"
 import { readNodeConfig, nodeConfigPath } from "../../../node/src/config.ts"
 import { str, UsageError, type FlagKind, type Parsed } from "../args"
-import { resolveCredentials, type Env } from "../credentials"
+import { resolveCredentials, type Credentials, type Env } from "../credentials"
+import { isInsecureStoredURL, storedInsecureWarning } from "../bootstrap/enrollment/policy.ts"
 import { clientFor } from "../http"
 import { hubLaunchDriver } from "./launch-driver.ts"
 import { errorCodeOf, issuesText, PlanRefusal } from "./contributors.ts"
@@ -94,7 +95,7 @@ const CONSENT_FLAGS = { escalate: "bool", "confirm-activation": "bool", "allow-d
 
 /** The flags of each command (args.ts CommandSpec). */
 export const BOOTSTRAP_FLAGS: Readonly<Record<string, Readonly<Record<string, FlagKind>>>> = {
-  "machine enroll": { server: "string", name: "string", reenroll: "bool", "no-verify": "bool" },
+  "machine enroll": { server: "string", name: "string", reenroll: "bool", "no-verify": "bool", "allow-insecure-http": "bool" },
   "machine status": { "no-verify": "bool" },
   "setup discover": {},
   "setup preview": { profile: "string", manifest: "string", out: "string", enrollment: "string", "workspace-root": "multi", "verify-launch": "string", server: "string", name: "string", ...CONSENT_FLAGS },
@@ -214,11 +215,28 @@ function readState(snapshot: DiscoverySnapshot): BootstrapState {
   }
 }
 
+/**
+ * This shell's hub login for the verification launch; a stored plain-http, non-loopback login is warned about once
+ * on stderr, as every `hub` command does.
+ */
+export function launchCredentials(io: Pick<SetupIo, "env" | "home" | "stderr">): () => Credentials | undefined {
+  let warned = false
+  return () => {
+    const found = resolveCredentials(io.env as Env, io.home)
+    if (found?.source === "login" && !warned && isInsecureStoredURL(found.url)) {
+      warned = true
+      io.stderr(`hubctl: warning: ${storedInsecureWarning(found.url)}\n`)
+    }
+    return found
+  }
+}
+
 /** The verification launch over the hub launch API, with this shell's hub login (resolved when it starts). */
 function launchDriverFor(io: SetupIo) {
   const store = credentialStoreFor(io.env, io.home)
+  const login = launchCredentials(io)
   const client = () => {
-    const credentials = resolveCredentials(io.env as Env, io.home)
+    const credentials = login()
     if (!credentials) throw new Error("not logged in to the hub (run `hub login --scope sessions:launch`; an app token launches under a grant with verb launch)")
     return clientFor(credentials)
   }
@@ -327,9 +345,10 @@ async function machine(verb: string, flags: Parsed["flags"], io: SetupIo, json:
     return printMachine(io, json, r.envelope, r.exit)
   }
   const server = str(flags, "server")
-  if (!server) throw new UsageError("needs --server <hub URL> (https; plain http only for a loopback hub)")
+  if (!server) throw new UsageError("needs --server <hub URL> (https; plain http only for a loopback hub, or a private-network IP address with --allow-insecure-http)")
   const r = await machineEnroll({
     server: server.replace(/\/+$/, ""),
+    ...(flags["allow-insecure-http"] === true ? { allowInsecureHTTP: true } : {}),
     ...(str(flags, "name") ? { machineName: str(flags, "name")! } : {}),
     store: credentialStoreFor(io.env, io.home, { migrate: true }),
     ...(flags.reenroll === true ? { reenroll: true } : {}),

package/packages/cli/src/setup/runtime.ts

@@ -447,8 +447,9 @@ export function createSetupRuntime(deps: RuntimeDeps): SetupRuntime {
 
 /** What `machine enroll` (and an inline enrollment) shows while it waits; never a credential. */
 export function enrollPromptText(p: EnrollPrompt): string {
-  if (p.autoApproved) return "hubctl: the local hub approved this machine by itself\n"
-  return `hubctl: approve this machine on the hub: ${p.approveURL}\nhubctl: and check it shows the code ${p.userCode} (it expires at ${new Date(p.expiresAt).toISOString()})\n${p.warning ? `hubctl: warning: ${p.warning}\n` : ""}`
+  const insecure = p.insecure ? `hubctl: warning: ${p.insecure}\n` : ""
+  if (p.autoApproved) return `${insecure}hubctl: the local hub approved this machine by itself\n`
+  return `${insecure}hubctl: approve this machine on the hub: ${p.approveURL}\n${p.localURL ? `hubctl: (on this machine: ${p.localURL})\n` : ""}hubctl: and check it shows the code ${p.userCode} (it expires at ${new Date(p.expiresAt).toISOString()})\n${p.warning ? `hubctl: warning: ${p.warning}\n` : ""}`
 }
 
 export function launchReportText(r: LaunchReport): string {

package/packages/cli/src/spoke-services.ts

@@ -18,7 +18,7 @@ export type ServiceVerb = (typeof SERVICE_VERBS)[number]
 export const isServiceVerb = (verb: string | undefined): verb is ServiceVerb => (SERVICE_VERBS as readonly string[]).includes(verb ?? "")
 
 /** Where config.json and the hub state dir are (shared by every hub spoke). */
-const HUB_PLACES = ["HUB_SPOKE_CONFIG", "XDG_CONFIG_HOME", "HUB_STATE_DIR"] as const
+const HUB_PLACES = ["HUB_SPOKE_CONFIG", "XDG_CONFIG_HOME", "HUB_STATE_DIR", "XDG_STATE_HOME"] as const
 
 export const CLAUDE_CODE_SERVICE: ServiceSpec = {
   service: "claude-code",

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}` : ""}`
+    },
+  },
+]