@huynle/hub 0.7.4 → 0.8.0

package/packages/protocol/src/profiles.ts

@@ -0,0 +1,301 @@
+// Shared agent profiles, skills and commands (HWA-02 contract; registry HWA-14, protocol HWA-15, adapters HWA-16/17/
+// 18, UI HWA-19). A profile is a versioned, hub-stored bundle (agent instructions, skills, commands) that can be
+// assigned to a running session. Distinct from runtime.profile (sandbox configuration) and from roles and grants:
+// assigning a profile confers no authority.
+//
+// Invariants frozen here:
+// - Versions are immutable; edits create a new version. Running sessions never change silently: an assignment
+//   pins a version, and a newer version only reaches a session through an explicit re-apply.
+// - Application is session-specific and acknowledged by the spoke (applied | rejected | unsupported) with the
+//   harness's reason. No adapter may rewrite global harness config; adapters write session-scoped state only.
+// - Spokes announce the spoke feature `profileApply` (constant below) to receive the `profileApply` op; the hub
+//   never sends it to a spoke that did not announce it, and reports `unsupported` instead.
+// - (HWA-15, additive) The spoke answers the op with a ProfileApplyResult echoing the session, profile, version and
+//   digest it applied; an answer naming anything else is stale. "restart_required": accepted, effective only after
+//   the harness session restarts. An assignment keeps the requested pin (profileID, version) and, apart, the
+//   `effective` version the session last confirmed (applied or partial).
+import { DESCRIPTION_MAX, isLabel, isSlug, isText, metadataProblem, tagsProblem, type RecordState, type Revisioned } from "./contracts.ts"
+import { isObj } from "./wire.ts"
+
+export const PROFILE_LIMITS = {
+  profilesPerUser: 200,
+  /** Retained versions per profile (older versions stay readable while any assignment pins them). */
+  versionsPerProfile: 100,
+  skillsPerProfile: 32,
+  commandsPerProfile: 64,
+  /** Characters of instructions, of each skill body and of each command template. */
+  instructionsChars: 32_000,
+  skillChars: 32_000,
+  commandChars: 8_000,
+  /** Total serialized size of one version. */
+  versionBytes: 512 * 1024,
+  /** (RP-08, additive) Project names one profile lists. */
+  projectsPerProfile: 16,
+} as const
+
+export const PROFILE_SCOPES = ["profiles:read", "profiles:manage", "profiles:assign"] as const
+
+/** The spoke feature and op name for applying a profile to one session. */
+export const PROFILE_APPLY_FEATURE = "profileApply"
+
+export interface ProfileSkill {
+  readonly name: string
+  readonly description: string
+  readonly body: string
+}
+
+export interface ProfileCommand {
+  readonly name: string
+  readonly description: string
+  readonly template: string
+}
+
+export interface ProfileVersionContent {
+  readonly instructions?: string
+  /** Preferred model "provider/model"; adapters may ignore it with a reported reason. */
+  readonly model?: string
+  readonly skills: readonly ProfileSkill[]
+  readonly commands: readonly ProfileCommand[]
+}
+
+export interface AgentProfile extends Revisioned {
+  readonly v: 1
+  readonly id: string
+  readonly name: string
+  readonly title: string
+  readonly description?: string
+  readonly state: RecordState
+  readonly tags?: readonly string[]
+  /**
+   * (RP-08, additive) Optional bounded key/value details (the shared metadataProblem rule: ≤ 32 slug keys, values
+   * 1–200 characters, never secrets), e.g. `owner`, `purpose`. On the profile record, not on versions.
+   */
+  readonly metadata?: Readonly<Record<string, string>>
+  /** (RP-08, additive) Project names the profile is meant for (≤ projectsPerProfile, unique; filters). */
+  readonly projects?: readonly string[]
+  readonly latestVersion: number
+  readonly updatedAt: number
+}
+
+export interface AgentProfileVersion {
+  readonly v: 1
+  readonly profileID: string
+  readonly version: number
+  readonly content: ProfileVersionContent
+  /** sha256 hex of the canonical JSON of `content` (adapters echo it in the acknowledgment). */
+  readonly digest: string
+  readonly createdAt: number
+}
+
+/** A session's pinned profile version and the latest acknowledgment for it. */
+export interface ProfileAssignment extends Revisioned {
+  readonly v: 1
+  readonly sessionID: string
+  readonly profileID: string
+  readonly version: number
+  readonly ack?: ProfileAck
+  /** (HWA-15) What the session runs now; absent until a spoke confirmed a version. */
+  readonly effective?: ProfileEffective
+}
+
+export type ProfileAckStatus = "pending" | "applied" | "partial" | "rejected" | "unsupported" | "restart_required"
+export const PROFILE_ACK_STATUSES: readonly ProfileAckStatus[] = ["pending", "applied", "partial", "rejected", "unsupported", "restart_required"]
+
+export interface ProfileAck {
+  readonly status: ProfileAckStatus
+  readonly digest: string
+  /** Per-part outcomes (e.g. "model ignored: harness pins model at launch"); bounded, no secrets. */
+  readonly notes?: readonly string[]
+  readonly at: number
+  /** (HWA-15) With pending: no spoke reports the session now; the hub applies the pin when one does. */
+  readonly offline?: true
+}
+
+/** (HWA-15) The version a session last confirmed running (applied or partial), kept across later pins. */
+export interface ProfileEffective {
+  readonly profileID: string
+  readonly version: number
+  readonly digest: string
+  readonly status: "applied" | "partial"
+  readonly at: number
+}
+
+export const PROFILE_EVENT_TYPES = ["profile.created", "profile.version.created", "profile.archived", "profile.assigned", "profile.ack"] as const
+
+/** Why a profile version body is not acceptable, or undefined. */
+export function profileContentProblem(v: unknown): string | undefined {
+  if (!isObj(v)) return "content must be an object"
+  if (v.instructions !== undefined && !isText(v.instructions, PROFILE_LIMITS.instructionsChars)) return `instructions must be at most ${PROFILE_LIMITS.instructionsChars} characters`
+  if (v.model !== undefined && (typeof v.model !== "string" || !/^[A-Za-z0-9._-]{1,80}\/[A-Za-z0-9._:/-]{1,200}$/.test(v.model))) return "model must be provider/model"
+  const parts: [unknown, number, number, "body" | "template", string][] = [
+    [v.skills, PROFILE_LIMITS.skillsPerProfile, PROFILE_LIMITS.skillChars, "body", "skills"],
+    [v.commands, PROFILE_LIMITS.commandsPerProfile, PROFILE_LIMITS.commandChars, "template", "commands"],
+  ]
+  for (const [list, max, chars, field, label] of parts) {
+    if (!Array.isArray(list) || list.length > max) return `${label} must be a list of at most ${max}`
+    const names = new Set<string>()
+    for (const item of list) {
+      if (!isObj(item) || !isSlug(item.name)) return `each of ${label} needs a slug name`
+      if (names.has(item.name)) return `${label} names must be unique (${item.name})`
+      names.add(item.name)
+      if (!isLabel(item.description, 300)) return `${label}.${item.name}.description must be 1–300 characters`
+      if (!isText(item[field], chars) || (item[field] as string).trim() === "") return `${label}.${item.name}.${field} must be 1–${chars} characters`
+    }
+  }
+  if (new TextEncoder().encode(JSON.stringify(v)).length > PROFILE_LIMITS.versionBytes) return "profile version is too large"
+  return undefined
+}
+
+/** (RP-08) Why a profile's `projects` is not acceptable, or undefined (absent is fine). */
+export function profileProjectsProblem(v: unknown): string | undefined {
+  if (v === undefined) return undefined
+  const max = PROFILE_LIMITS.projectsPerProfile
+  if (!Array.isArray(v) || v.length > max || !v.every((p) => isLabel(p)) || new Set(v).size !== v.length) return `projects must be at most ${max} unique project names`
+  return undefined
+}
+
+/** Why a create-profile body is not acceptable, or undefined. */
+export function profileInputProblem(v: unknown): string | undefined {
+  if (!isObj(v)) return "body must be an object"
+  if (!isSlug(v.name)) return "name must be 2–40 lowercase letters, digits or dashes"
+  if (!isLabel(v.title)) return "title must be 1–120 characters of text"
+  if (v.description !== undefined && !isText(v.description, DESCRIPTION_MAX)) return `description must be at most ${DESCRIPTION_MAX} characters`
+  return tagsProblem(v.tags) ?? metadataProblem(v.metadata) ?? profileProjectsProblem(v.projects) ?? profileContentProblem(v.content)
+}
+
+// ---------- application (HWA-15) ----------
+
+/** What a spoke answers to profileApply (never "pending": the hub alone records that). */
+export type ProfileApplyStatus = Exclude<ProfileAckStatus, "pending">
+export const PROFILE_APPLY_STATUSES: readonly ProfileApplyStatus[] = ["applied", "partial", "rejected", "unsupported", "restart_required"]
+
+export const PROFILE_APPLY_LIMITS = {
+  /** Notes per acknowledgment. */
+  notes: 16,
+  /** Characters per note. */
+  noteChars: 300,
+} as const
+
+/** Hub → spoke: apply one immutable profile version to one session (feature `profileApply`). */
+export interface ProfileApplyRequest {
+  readonly op: "profileApply"
+  readonly sessionID: string
+  readonly profileID: string
+  readonly version: number
+  /** sha256 hex of canonicalProfileJSON(content); the spoke checks it before applying and echoes it. */
+  readonly digest: string
+  readonly content: ProfileVersionContent
+}
+
+/** Spoke → hub: the outcome for exactly the session, profile, version and digest it was asked to apply. */
+export interface ProfileApplyResult {
+  readonly sessionID: string
+  readonly profileID: string
+  readonly version: number
+  readonly digest: string
+  readonly status: ProfileApplyStatus
+  /** Bounded (PROFILE_APPLY_LIMITS), plain text; never secret values or profile content. */
+  readonly notes?: readonly string[]
+}
+
+const DIGEST = /^[0-9a-f]{64}$/
+const PROFILE_REF = /^[A-Za-z0-9_.:-]{1,100}$/
+const CONTENT_KEYS = new Set(["instructions", "model", "skills", "commands"])
+const SKILL_KEYS = new Set(["name", "description", "body"])
+const COMMAND_KEYS = new Set(["name", "description", "template"])
+const isVersion = (v: unknown): v is number => typeof v === "number" && Number.isSafeInteger(v) && v >= 1
+const onlyKeys = (v: Record<string, unknown>, keys: ReadonlySet<string>) => Object.keys(v).every((k) => keys.has(k))
+
+/** Why `v` is not an acceptable profileApply request, or undefined. Content is exactly the known fields. */
+export function profileApplyRequestProblem(v: unknown): string | undefined {
+  if (!isObj(v) || v.op !== "profileApply") return "op must be profileApply"
+  if (typeof v.sessionID !== "string" || !PROFILE_REF.test(v.sessionID)) return "sessionID must be a session ID"
+  if (typeof v.profileID !== "string" || !PROFILE_REF.test(v.profileID)) return "profileID must be a profile ID"
+  if (!isVersion(v.version)) return "version must be a version number"
+  if (typeof v.digest !== "string" || !DIGEST.test(v.digest)) return "digest must be 64 lowercase hex characters"
+  const content = v.content
+  if (!isObj(content) || !onlyKeys(content, CONTENT_KEYS)) return "content must hold only instructions, model, skills and commands"
+  if (Array.isArray(content.skills) && !content.skills.every((s) => isObj(s) && onlyKeys(s, SKILL_KEYS))) return "skills hold only name, description and body"
+  if (Array.isArray(content.commands) && !content.commands.every((c) => isObj(c) && onlyKeys(c, COMMAND_KEYS))) return "commands hold only name, description and template"
+  return profileContentProblem(content)
+}
+
+/**
+ * Why `v` is not an acceptable profileApply result, or undefined. With `request`, a result that names another
+ * session, profile, version or digest is stale (the hub never records it).
+ */
+export function profileApplyResultProblem(v: unknown, request?: Pick<ProfileApplyRequest, "sessionID" | "profileID" | "version" | "digest">): string | undefined {
+  if (!isObj(v)) return "result must be an object"
+  if (!(PROFILE_APPLY_STATUSES as readonly unknown[]).includes(v.status)) return `status must be one of ${PROFILE_APPLY_STATUSES.join(", ")}`
+  if (v.notes !== undefined) {
+    const { notes: max, noteChars } = PROFILE_APPLY_LIMITS
+    if (!Array.isArray(v.notes) || v.notes.length > max || !v.notes.every((n) => typeof n === "string" && n.length <= noteChars && !/[\p{Cc}\p{Cf}\u2028\u2029]/u.test(n))) {
+      return `notes must be at most ${max} lines of at most ${noteChars} printable characters`
+    }
+  }
+  if (typeof v.sessionID !== "string" || typeof v.profileID !== "string" || !isVersion(v.version) || typeof v.digest !== "string" || !DIGEST.test(v.digest)) {
+    return "result must echo sessionID, profileID, version and digest"
+  }
+  if (!request) return undefined
+  if (v.sessionID !== request.sessionID) return "stale: the result names another session"
+  if (v.profileID !== request.profileID) return "stale: the result names another profile"
+  if (v.version !== request.version) return "stale: the result names another version"
+  if (v.digest !== request.digest) return "stale: the result names another digest"
+  return undefined
+}
+
+/** JSON with object keys sorted at every level (undefined members dropped): what the version digest hashes. */
+export function canonicalProfileJSON(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonicalProfileJSON).join(",")}]`
+  if (isObj(value)) {
+    const keys = Object.keys(value).filter((k) => value[k] !== undefined).sort()
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalProfileJSON(value[k])}`).join(",")}}`
+  }
+  return JSON.stringify(value)
+}
+
+/** One part of a command template: literal text, a `{{param}}` or a `{{secret:NAME}}` reference. */
+export type ProfileTemplatePart = { readonly text: string } | { readonly param: string } | { readonly secret: string; readonly raw: string }
+
+const TEMPLATE_PARAM = /^[a-z][a-z0-9_]{0,39}$/
+const TEMPLATE_SECRET = /^[A-Z][A-Z0-9_]{0,63}$/
+const SECRET_PREFIX = "secret:"
+
+/**
+ * Splits a command template (HWA-14 syntax: `{{param}}`, `{{arguments}}`, `{{secret:NAME}}`, `\{{` for a literal
+ * `{{`; nothing else) into parts, or says why it is refused. Problems name positions, never template text.
+ */
+export function profileTemplateParts(template: string): ProfileTemplatePart[] | string {
+  const out: ProfileTemplatePart[] = []
+  let text = ""
+  let i = 0
+  while (i < template.length) {
+    if (template.startsWith("\\{{", i)) {
+      text += "{{"
+      i += 3
+      continue
+    }
+    if (!template.startsWith("{{", i)) {
+      text += template[i]
+      i++
+      continue
+    }
+    const end = template.indexOf("}}", i + 2)
+    if (end < 0) return `unclosed placeholder at character ${i + 1}`
+    const inner = template.slice(i + 2, end).trim()
+    if (inner.startsWith(SECRET_PREFIX)) {
+      if (!TEMPLATE_SECRET.test(inner.slice(SECRET_PREFIX.length))) return `secret reference at character ${i + 1} must be {{secret:NAME}} (uppercase letters, digits, _)`
+      if (text) out.push({ text })
+      text = ""
+      out.push({ secret: inner.slice(SECRET_PREFIX.length), raw: template.slice(i, end + 2) })
+    } else {
+      if (!TEMPLATE_PARAM.test(inner)) return `placeholder at character ${i + 1} is not a {{name}} parameter (no expression, condition or filter is allowed; write \\{{ for a literal {{)`
+      if (text) out.push({ text })
+      text = ""
+      out.push({ param: inner })
+    }
+    i = end + 2
+  }
+  if (text) out.push({ text })
+  return out
+}

package/packages/protocol/src/teams.ts

@@ -0,0 +1,204 @@
+// Persistent teams (HWA-02 contract; definitions HWA-33, enforcement HWA-34, staffing HWA-35, intake HWA-36,
+// API/SDK/CLI/MCP HWA-37, Watchtower team views HWA-38/39, team-aware discovery HWA-40). Decisions zltiwb4s,
+// 5etngvgm (external contact), r3vv4eon (no-team sessions unchanged), qxzrdc6c (@@role#team).
+//
+// A team is a versioned definition (roles, one entry role, communication mode and paths, tags/metadata). It grants
+// no authority: staffing a role with a session needs the existing grants. Membership is many-to-many: a session
+// may hold roles in several teams, and more than one role in one team.
+//
+// teamDeliveryVerdict below is the normative delivery rule; HWA-34 calls it from central message delivery and
+// must not re-derive it.
+import { DESCRIPTION_MAX, isLabel, isSlug, isText, metadataProblem, tagsProblem, type RecordState, type Revisioned } from "./contracts.ts"
+import { isObj } from "./wire.ts"
+
+export const TEAM_LIMITS = {
+  teamsPerUser: 100,
+  rolesPerTeam: 32,
+  edgesPerTeam: 256,
+  /** Sessions staffed per role (several sessions may share a role). */
+  sessionsPerRole: 16,
+  /** Open intake items per team. */
+  openIntakePerTeam: 500,
+} as const
+
+export const TEAM_SCOPES = ["teams:read", "teams:manage", "teams:submit"] as const
+
+/** "open": every member may msg/ask every other member (two-way). "restricted": only the drawn edges. */
+export type TeamMode = "open" | "restricted"
+
+/** Message kinds a path permits. Replies to a permitted ask never need a path. */
+export type TeamMessageKind = "msg" | "ask"
+
+export interface TeamRole {
+  readonly name: string
+  readonly label?: string
+  readonly description?: string
+  /** Decision 5etngvgm: holders of this role may contact sessions outside all their teams. Default false. */
+  readonly externalContact?: boolean
+}
+
+export interface TeamEdge {
+  readonly from: string
+  readonly to: string
+  readonly kinds: readonly TeamMessageKind[]
+  /** "two-way": `to` may also contact `from` with the same kinds. */
+  readonly direction: "one-way" | "two-way"
+}
+
+export interface TeamDefinition extends Revisioned {
+  readonly v: 1
+  readonly id: string
+  /** Slug used in addresses: `@@role#name`. Unique per user. */
+  readonly name: string
+  readonly title: string
+  readonly description?: string
+  readonly state: RecordState
+  readonly mode: TeamMode
+  readonly roles: readonly TeamRole[]
+  /** The intake role; receives submitted work and supervises members (via workspace supervision). */
+  readonly entryRole: string
+  /** Ignored in open mode (kept so switching modes is lossless). */
+  readonly edges: readonly TeamEdge[]
+  readonly tags?: readonly string[]
+  readonly metadata?: Readonly<Record<string, string>>
+  readonly updatedAt: number
+}
+
+/** A session staffed in a role of a team (HWA-35). A replacement is a new generation of the same slot. */
+export interface TeamStaffing extends Revisioned {
+  readonly v: 1
+  readonly id: string
+  readonly teamID: string
+  readonly role: string
+  readonly sessionID: string
+  readonly generation: number
+  readonly since: number
+  readonly until?: number
+}
+
+/** Work submitted to a team (HWA-36): routed to the entry role, tracked as a workspace assignment. */
+export interface TeamIntake extends Revisioned {
+  readonly v: 1
+  readonly id: string
+  readonly teamID: string
+  readonly title: string
+  readonly source: { readonly kind: "user" } | { readonly kind: "app"; readonly tokenID: string } | { readonly kind: "session"; readonly sessionID: string }
+  readonly ref?: string
+  readonly assignmentID?: string
+  readonly status: "queued" | "routed" | "done" | "cancelled" | "failed"
+  readonly createdAt: number
+}
+
+export const TEAM_EVENT_TYPES = ["team.created", "team.updated", "team.archived", "team.staffed", "team.unstaffed", "team.intake", "team.denied"] as const
+
+// ---- Addressing (decision qxzrdc6c) --------------------------------------------------------------------------
+
+export interface TeamRoleAddress {
+  readonly role: string
+  readonly project?: string
+  readonly team: string
+}
+
+/**
+ * Parses `@@role#team` and `@@role.project#team`. Undefined for anything else, including a plain `@@role`
+ * (which parseAddress handles; a team-less role address that resolves in several teams is ambiguous: HWA-34).
+ */
+export function parseTeamRoleAddress(addr: string): TeamRoleAddress | undefined {
+  const match = /^@@([a-z0-9-]{2,40})(?:\.([^./\s#]+))?#([a-z0-9-]{2,40})$/i.exec(addr)
+  if (!match) return undefined
+  const [, role, project, team] = match
+  if (role !== role!.toLowerCase() || team !== team!.toLowerCase()) return undefined
+  return project ? { role: role!, project: project.toLowerCase(), team: team! } : { role: role!, team: team! }
+}
+
+export const formatTeamRoleAddress = (a: TeamRoleAddress): string => `@@${a.role}${a.project ? `.${a.project}` : ""}#${a.team}`
+
+// ---- Delivery rule (decisions zltiwb4s, 5etngvgm, r3vv4eon) -----------------------------------------------------
+
+/** One (team, role) a session holds. */
+export interface TeamSeat {
+  readonly teamID: string
+  readonly role: string
+}
+
+export interface DeliveryQuestion {
+  readonly kind: TeamMessageKind | "reply"
+  /** The recipient is the user (@me escalation). */
+  readonly toUser: boolean
+  /** For replies: the ask being answered was itself delivered (permitted). */
+  readonly replyToPermittedAsk: boolean
+  readonly senderSeats: readonly TeamSeat[]
+  readonly recipientSeats: readonly TeamSeat[]
+  /** Explicit team context (`#team` address or API field): only that team's policy is consulted. */
+  readonly teamID?: string
+  readonly teams: ReadonlyMap<string, Pick<TeamDefinition, "mode" | "edges" | "roles" | "state">>
+}
+
+export type DeliveryVerdict =
+  | { readonly allow: true; readonly via: "user" | "reply" | "no_team" | "team"; readonly teamID?: string }
+  | { readonly allow: false; readonly reason: "policy" | "external" | "not_member" }
+
+function edgePermits(team: Pick<TeamDefinition, "mode" | "edges">, from: string, to: string, kind: TeamMessageKind): boolean {
+  if (team.mode === "open") return true
+  return team.edges.some((e) => e.kinds.includes(kind) && ((e.from === from && e.to === to) || (e.direction === "two-way" && e.from === to && e.to === from)))
+}
+
+/**
+ * Whether central may deliver a msg/ask/reply between two sessions under team policy. Order:
+ * 1. @me escalation and replies to a permitted ask: always allowed.
+ * 2. A sender in no (active) team: today's behavior, allowed (r3vv4eon). Inbound to team members included.
+ * 3. With a team context: the sender must hold a seat there; only that team decides.
+ * 4. Shared teams: allowed if at least one shared team permits sender role → recipient role for this kind.
+ * 5. No shared team: allowed only if one of the sender's roles opts into external contact (5etngvgm).
+ */
+export function teamDeliveryVerdict(q: DeliveryQuestion): DeliveryVerdict {
+  if (q.toUser) return { allow: true, via: "user" }
+  if (q.kind === "reply" && q.replyToPermittedAsk) return { allow: true, via: "reply" }
+  const active = (s: TeamSeat): boolean => q.teams.get(s.teamID)?.state === "active"
+  const sender = q.senderSeats.filter(active)
+  const recipient = q.recipientSeats.filter(active)
+  if (sender.length === 0) return { allow: true, via: "no_team" }
+  const kind: TeamMessageKind = q.kind === "reply" ? "msg" : q.kind
+  const consider = q.teamID === undefined ? sender : sender.filter((s) => s.teamID === q.teamID)
+  if (q.teamID !== undefined && consider.length === 0) return { allow: false, reason: "not_member" }
+  let shared = false
+  for (const s of consider) {
+    for (const r of recipient) {
+      if (r.teamID !== s.teamID) continue
+      shared = true
+      if (edgePermits(q.teams.get(s.teamID)!, s.role, r.role, kind)) return { allow: true, via: "team", teamID: s.teamID }
+    }
+  }
+  if (shared || q.teamID !== undefined) return { allow: false, reason: "policy" }
+  const external = sender.some((s) => q.teams.get(s.teamID)!.roles.some((r) => r.name === s.role && r.externalContact === true))
+  return external ? { allow: true, via: "team" } : { allow: false, reason: "external" }
+}
+
+// ---- Input checks -----------------------------------------------------------------------------------------------
+
+export function teamInputProblem(v: unknown): string | undefined {
+  if (!isObj(v)) return "body must be an object"
+  if (!isSlug(v.name)) return "name must be 2–40 lowercase letters, digits or dashes"
+  if (!isLabel(v.title)) return "title must be 1–120 characters of text"
+  if (v.description !== undefined && !isText(v.description, DESCRIPTION_MAX)) return `description must be at most ${DESCRIPTION_MAX} characters`
+  if (v.mode !== "open" && v.mode !== "restricted") return "mode must be open or restricted"
+  if (!Array.isArray(v.roles) || v.roles.length === 0 || v.roles.length > TEAM_LIMITS.rolesPerTeam) return `roles must list 1–${TEAM_LIMITS.rolesPerTeam} roles`
+  const names = new Set<string>()
+  for (const role of v.roles) {
+    if (!isObj(role) || !isSlug(role.name)) return "each role needs a slug name"
+    if (names.has(role.name)) return `role ${role.name} is listed twice`
+    names.add(role.name)
+    if (role.label !== undefined && !isLabel(role.label)) return `role ${role.name} label must be 1–120 characters`
+    if (role.externalContact !== undefined && typeof role.externalContact !== "boolean") return `role ${role.name} externalContact must be true or false`
+  }
+  if (typeof v.entryRole !== "string" || !names.has(v.entryRole)) return "entryRole must name one of the roles"
+  const edges = v.edges ?? []
+  if (!Array.isArray(edges) || edges.length > TEAM_LIMITS.edgesPerTeam) return `edges must be a list of at most ${TEAM_LIMITS.edgesPerTeam}`
+  for (const e of edges) {
+    if (!isObj(e) || typeof e.from !== "string" || typeof e.to !== "string" || !names.has(e.from) || !names.has(e.to)) return "each edge must connect two listed roles"
+    if (e.from === e.to) return "an edge must connect two different roles"
+    if (!Array.isArray(e.kinds) || e.kinds.length === 0 || !e.kinds.every((k) => k === "msg" || k === "ask")) return "edge kinds must be msg and/or ask"
+    if (e.direction !== "one-way" && e.direction !== "two-way") return "edge direction must be one-way or two-way"
+  }
+  return tagsProblem(v.tags) ?? metadataProblem(v.metadata)
+}

package/packages/runtime-openshell/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-runtime-openshell",
-  "version": "0.7.4",
+  "version": "0.8.0",
   "private": true,
   "description": "The `openshell` runtime of `hub node`: launches in NVIDIA OpenShell sandboxes, driven through the openshell CLI (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/runtime-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-runtime-sdk",
-  "version": "0.7.4",
+  "version": "0.8.0",
   "private": true,
   "description": "The Runtime interface `hub node` runtimes implement (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-sdk",
-  "version": "0.7.4",
+  "version": "0.8.0",
   "private": true,
   "description": "Typed client for the hub's /api/agent (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/sdk/src/address.ts

@@ -9,8 +9,12 @@ export const validName = (name: string): boolean => NAME.test(name)
 
 export type Address = { kind: "id"; id: string } | { kind: "name"; name: string; project?: string } | { kind: "role"; role: string; project?: string }
 
-/** A project scope: any non-empty run of characters without dots, slashes or spaces, compared lowercased. */
-const SCOPED = /^([a-z0-9-]{2,40})(?:\.([^./\s]+))?$/i
+/**
+ * A project scope: any non-empty run of characters without dots, slashes, spaces or `#`, compared lowercased.
+ * `#` is the team separator (`@@role#team`, `@@role.project#team`: protocol parseTeamRoleAddress), never part of
+ * a plain address, so a team address is never resolved as a global role.
+ */
+const SCOPED = /^([a-z0-9-]{2,40})(?:\.([^./\s#]+))?$/i
 
 /** `ses_…` (an ID or ID prefix), `@name[.project]` or `@@role[.project]`; undefined when malformed. */
 export function parseAddress(addr: string): Address | undefined {
@@ -23,3 +27,47 @@ export function parseAddress(addr: string): Address | undefined {
   const scope = project ? { project } : {}
   return role ? { kind: "role", role: match[1]!, ...scope } : { kind: "name", name: match[1]!, ...scope }
 }
+
+/** What a refused address answers: the accepted forms, and a hint derived from the address's shape only. */
+export interface AddressProblem {
+  readonly message: string
+  readonly hint: string
+}
+
+/** The address forms, as error messages list them. */
+export const ADDRESS_FORMS = "ses_…, @name, @@role or @@role#team"
+const FORMS_HINT = "Addresses are ses_… (an ID or a prefix), @name[.project], @@role[.project], @@role#team (a role in one of your teams; quote # in a shell) or @me"
+const TEAM_FORMS = "@@role#team or @@role.project#team"
+const SLUG = /^[a-z0-9-]{2,40}$/
+/** A well-formed team address (protocol parseTeamRoleAddress's syntax). */
+const TEAM_ADDRESS = /^@@[a-z0-9-]{2,40}(?:\.[^./\s#]+)?#[a-z0-9-]{2,40}$/
+
+/**
+ * Why `addr` is not an address here (parseAddress refused it). Pure syntax: it never says whether a session, role
+ * or team exists, and it quotes only parts of the input that are valid name slugs (never free text).
+ */
+export function addressProblem(addr: string): AddressProblem {
+  const message = `Not an address: use ${ADDRESS_FORMS}`
+  const hash = addr.indexOf("#")
+  if (hash < 0) {
+    const lowercase = /[A-Z]/.test(addr) && parseAddress(addr.toLowerCase()) !== undefined
+    return { message, hint: lowercase ? `Names and roles are lowercase. ${FORMS_HINT}` : FORMS_HINT }
+  }
+  if (TEAM_ADDRESS.test(addr)) {
+    return {
+      message: "A team address (@@role#team) is not accepted here: use ses_…, @name or @@role",
+      hint: "Team addresses work for messages and reads (msg, ask, who, show, log, events); to act on a session, name it: ses_… or @name (see who)",
+    }
+  }
+  const head = addr.slice(0, hash)
+  const team = addr.slice(hash + 1)
+  const doubled = head.startsWith("@@")
+  const name = head.startsWith("@") ? head.slice(doubled ? 2 : 1).split(".")[0]! : undefined
+  if (name !== undefined && !doubled && SLUG.test(name) && SLUG.test(team)) {
+    return { message, hint: `A team address names a role, not a session: @@${name}#${team} (the ${name} role of team ${team}), or @${name} without #team for the session named ${name}` }
+  }
+  if (name !== undefined && SLUG.test(name.toLowerCase()) && SLUG.test(team.toLowerCase())) {
+    return { message, hint: `Role and team names are lowercase: ${TEAM_FORMS}` }
+  }
+  return { message, hint: `Team addresses are ${TEAM_FORMS}: lowercase a-z, 0-9 and -, 2–40 characters (quote # in a shell)` }
+}