@huynle/hub 0.10.1 → 0.11.1

package/src/central/agent/decisions.ts

@@ -79,6 +79,23 @@ export const DECISION_TICK_MS = 30_000
 
 const OPTION_ID = /^[a-z0-9][a-z0-9_-]{0,31}$/
 
+/** (DC-1) Choice groups of a Decision, options per group, and characters of a group's label. */
+export const CHOICES_MAX = 12
+export const CHOICE_OPTIONS_MIN = 2
+export const CHOICE_OPTIONS_MAX = 6
+export const CHOICE_LABEL_MAX = 120
+const CHOICE_ID = /^[A-Za-z0-9_-]{1,8}$/
+/** (DC-1) What an ask is about, for the card's header (absent: a question). */
+export type DecisionKind = "question" | "plan" | "merge" | "release"
+export const DECISION_KINDS: readonly DecisionKind[] = ["question", "plan", "merge", "release"]
+
+/** (DC-1) One point of a structured ask: the user picks one of its options. */
+export interface DecisionChoice {
+  readonly id: string
+  readonly label: string
+  readonly options: readonly { readonly id: string; readonly label: string; readonly recommended?: true }[]
+}
+
 export interface DecisionOption {
   readonly id: string
   readonly label: string
@@ -88,6 +105,8 @@ export interface DecisionOption {
 
 export interface DecisionAnswer {
   readonly option?: string
+  /** (DC-1) A choices Decision: the option picked in each group (absent: answered with text only). */
+  readonly picks?: Readonly<Record<string, string>>
   readonly text?: string
   /** (AF4) "app": an app holding decisions:answer answered a confirm-tier Decision of its own session. */
   readonly answeredBy: "user" | "timeout" | "app"
@@ -124,7 +143,22 @@ export function appAnswerRefusal(decision: Pick<Decision, "tier" | "action" | "a
 }
 
 /** What answering a Decision does besides replying: an escalated permission request (P3-T8) or a grant request (P3-T9). */
-export type DecisionAction = PermissionAction | GrantRequestAction | ActAction
+export type DecisionAction = PermissionAction | GrantRequestAction | ActAction | TeamHopRenewAction | TeamItemAction
+
+/** Hub-created, tap-only action: an agent cannot authorize a team's hop budget renewal. */
+export interface TeamHopRenewAction {
+  readonly kind: "teamHopRenew"
+  readonly teamID: string
+}
+
+/** (TA2-7) Hub-created, tap-only: Extend or Stop one intake item that spent its budget or loops without progress. */
+export interface TeamItemAction {
+  readonly kind: "teamItem"
+  readonly teamID: string
+  readonly item: string
+  readonly reason: "budget" | "loop"
+  readonly pair?: readonly [string, string]
+}
 
 /**
  * (CON-06) A Concierge proposal (concierge/proposals.ts): answering `go` runs the act verb on the target AS THE USER
@@ -227,6 +261,9 @@ export interface Decision {
   readonly question: string
   readonly options: readonly DecisionOption[]
   readonly recommendation?: { readonly option: string; readonly why?: string }
+  /** (DC-1) Structured choices (an agent's ask only; never with options or an action). */
+  readonly choices?: readonly DecisionChoice[]
+  readonly kind?: DecisionKind
   readonly urgency: Urgency
   readonly tier: Tier
   readonly deadline?: number
@@ -257,6 +294,8 @@ export interface AskInput {
   readonly question: string
   readonly options?: readonly { readonly id: string; readonly label: string; readonly safe?: boolean }[]
   readonly recommendation?: { readonly option: string; readonly why?: string }
+  readonly choices?: readonly { readonly id: string; readonly label: string; readonly options: readonly { readonly id: string; readonly label: string; readonly recommended?: boolean }[] }[]
+  readonly kind?: DecisionKind
   readonly urgency?: Urgency
   readonly tier?: Tier
   /** From now. */
@@ -271,6 +310,8 @@ export interface AskInput {
 export interface AnswerInput {
   readonly option?: string
   readonly text?: string
+  /** (DC-1) One option per choice group. */
+  readonly picks?: Readonly<Record<string, string>>
   /** (CON-06) Absent = tap. */
   readonly via?: AnswerVia
 }
@@ -305,6 +346,8 @@ export interface DecisionsDeps {
   readonly changed?: (userID: string, decision: Decision) => void
   /** Runs Decisions' actions (escalations); a Decision with an action cannot be answered without it. */
   readonly act?: DecisionActor
+  /** Only the authenticated user's answer path; never answerByApp or the deadline sweep. */
+  readonly answered?: (userID: string, decision: Decision, by: UserActor) => Promise<void>
   /** (CON-06) Admits voice/text answers; without it every voice/text answer is refused. */
   readonly via?: ViaCheck
   /** (CON-06) Whether a session is one of the user's Concierge sessions (current or past): the Decision's `as`. */
@@ -364,6 +407,9 @@ function validate(input: AskInput) {
     if (typeof option !== "string" || !has(option)) throw invalid("The recommendation must name one of the options")
     recommendation = { option, ...(why === undefined ? {} : { why: cleanLabel(why, WHY_MAX, "The recommendation's reason") }) }
   }
+  const choices = input.choices === undefined ? undefined : validChoices(input.choices)
+  if (choices && options.length) throw invalid("An ask offers either options or choices, not both")
+  if (input.kind !== undefined && !DECISION_KINDS.includes(input.kind)) throw invalid(`kind is one of ${DECISION_KINDS.join(", ")}`)
   const urgency = input.urgency ?? "normal"
   if (!URGENCIES.includes(urgency)) throw invalid(`urgency is one of ${URGENCIES.join(", ")}`)
   const tier = input.tier ?? "confirm"
@@ -378,7 +424,62 @@ function validate(input: AskInput) {
   }
   const expiresInMs = input.expiresInMs ?? Math.min(ASK_EXPIRES_MAX_MS, Math.max(ASK_EXPIRES_MS, (deadlineMs ?? 0) + ASK_EXPIRES_MS))
   if (deadlineMs !== undefined && deadlineMs > expiresInMs) throw invalid("The deadline is after the ask expires")
-  return { options, recommendation, urgency, tier, deadlineMs, onTimeout, expiresInMs }
+  return { options, recommendation, choices, kind: input.kind, urgency, tier, deadlineMs, onTimeout, expiresInMs }
+}
+
+function validChoices(raw: unknown): DecisionChoice[] {
+  if (!Array.isArray(raw) || raw.length < 1 || raw.length > CHOICES_MAX) throw invalid(`choices are 1–${CHOICES_MAX} groups`)
+  const groups: DecisionChoice[] = []
+  for (const group of raw as Record<string, unknown>[]) {
+    if (typeof group?.id !== "string" || !CHOICE_ID.test(group.id)) throw invalid("Choice group ids are 1–8 letters, digits, - or _")
+    if (groups.some((g) => g.id === group.id)) throw invalid(`Choice group ${group.id} is given twice`)
+    const label = cleanLabel(group.label, CHOICE_LABEL_MAX, `Choice group ${group.id}'s label`)
+    const list = group.options
+    if (!Array.isArray(list) || list.length < CHOICE_OPTIONS_MIN || list.length > CHOICE_OPTIONS_MAX) throw invalid(`Choice group ${group.id} offers ${CHOICE_OPTIONS_MIN}–${CHOICE_OPTIONS_MAX} options`)
+    const options: { id: string; label: string; recommended?: true }[] = []
+    for (const option of list as Record<string, unknown>[]) {
+      if (typeof option?.id !== "string" || !OPTION_ID.test(option.id)) throw invalid("Option ids are 1–32 lowercase letters, digits, - or _")
+      if (options.some((o) => o.id === option.id)) throw invalid(`Option ${option.id} is given twice in ${group.id}`)
+      if (option.recommended !== undefined && typeof option.recommended !== "boolean") throw invalid("recommended must be true or false")
+      options.push({ id: option.id, label: cleanLabel(option.label, OPTION_LABEL_MAX, "An option label"), ...(option.recommended === true ? { recommended: true as const } : {}) })
+    }
+    if (options.filter((o) => o.recommended).length > 1) throw invalid(`Choice group ${group.id} has more than one recommended option`)
+    groups.push({ id: group.id, label, options })
+  }
+  return groups
+}
+
+/** (DC-1) An answer body's `picks`: undefined when absent, else {group: option} strings (checked against the Decision later). */
+export function answerPicks(raw: unknown): Record<string, string> | undefined {
+  if (raw === undefined) return undefined
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw) || Object.keys(raw).length > CHOICES_MAX) throw invalid("picks must be {group: option}")
+  // No prototype: a "__proto__" key stays an own key (an unknown group, refused later) instead of vanishing.
+  const out: Record<string, string> = Object.create(null)
+  for (const [group, option] of Object.entries(raw)) {
+    if (typeof option !== "string") throw invalid("picks must be {group: option}")
+    out[group] = option
+  }
+  return out
+}
+
+/** The audit detail of an answer: the option, the picks (validated IDs) or "text". */
+export function answerDetail(answer: DecisionAnswer | undefined): string {
+  if (answer?.option !== undefined) return answer.option
+  if (answer?.picks) return `picks ${Object.entries(answer.picks).map(([g, o]) => `${g}=${o}`).join(",")}`
+  return "text"
+}
+
+/** What the asker reads: the option, the picks ("D1: label [a]" per line) or the text, then the note. */
+function answerText(decision: Decision, choice: { option?: string; text?: string; picks?: Readonly<Record<string, string>> }, by?: string): string {
+  const head = `Decision ${decision.id}:${by ? ` ${by}` : ""}`
+  if (choice.picks && decision.choices) {
+    const lines = decision.choices.map((g) => `${g.id}: ${g.options.find((o) => o.id === choice.picks![g.id])?.label ?? choice.picks![g.id]} [${choice.picks![g.id]}]`)
+    return `${head}\n${lines.join("\n")}${choice.text ? `\n${choice.text}` : ""}`
+  }
+  const option = decision.options.find((o) => o.id === choice.option)
+  if (option) return `Decision ${decision.id}: ${option.label} [${option.id}]${by ? ` ${by}` : ""}${choice.text ? `\n${choice.text}` : ""}`
+  if (decision.choices) return `Decision ${decision.id}: no picks, text: ${choice.text}${by ? ` ${by}` : ""}`
+  return `Decision ${decision.id}: ${choice.text}${by ? ` ${by}` : ""}`
 }
 
 export class Decisions {
@@ -404,6 +505,7 @@ export class Decisions {
     if (actor.kind === "user") throw invalid("You are @me: the user cannot ask themselves")
     if (typeof input.question !== "string") throw invalid("question must be a string")
     const v = validate(input)
+    if (v.choices && extra.action) throw invalid("A hub action never uses choices")
     const about = [...new Set(input.about ?? (actor.kind === "session" ? [actor.sessionID] : []))]
     const { message } = await this.deps.delivery.send(userID, actor, "@me", "ask", input.question, { expiresInMs: v.expiresInMs })
     const asConcierge = actor.kind === "session" && (await this.isConcierge(userID, actor.sessionID))
@@ -416,6 +518,8 @@ export class Decisions {
       question: message.text,
       options: v.options,
       ...(v.recommendation ? { recommendation: v.recommendation } : {}),
+      ...(v.choices ? { choices: v.choices } : {}),
+      ...(v.kind ? { kind: v.kind } : {}),
       urgency: v.urgency,
       tier: v.tier,
       ...(v.deadlineMs === undefined ? {} : { deadline: message.at + v.deadlineMs }),
@@ -480,9 +584,13 @@ export class Decisions {
     const decision = await this.settle(userID, id, answer)
     if (!decision) throw gone()
     const note = decision.action ? await this.runAction(userID, decision, choice, by) : undefined
+    // The answer is settled and any action has completed. An involvement hook must not undo the user's answer.
+    if (this.deps.answered) {
+      try { await this.deps.answered(userID, decision, by) }
+      catch (cause) { console.error("[hub] user Decision involvement failed:", cause) }
+    }
     this.emit(userID, decision)
-    const option = decision.options.find((o) => o.id === choice.option)
-    const said = option ? `Decision ${id}: ${option.label} [${option.id}]${choice.text ? `\n${choice.text}` : ""}` : `Decision ${id}: ${choice.text}`
+    const said = answerText(decision, choice)
     const text = note ? `${said}\n${note}` : said
     return { decision, ...(await this.replyTo(userID, decision, text, by)) }
   }
@@ -496,7 +604,7 @@ export class Decisions {
   async answerByApp(
     userID: string,
     id: string,
-    input: { readonly option?: string; readonly text?: string },
+    input: { readonly option?: string; readonly text?: string; readonly picks?: Readonly<Record<string, string>> },
     app: AppAnswerer,
     checks: { readonly owned: (decision: Decision) => Promise<boolean>; readonly ready?: (decision: Decision) => void },
   ): Promise<{ decision: Decision; reply?: Message }> {
@@ -513,9 +621,7 @@ export class Decisions {
     const decision = await this.settle(userID, id, answer)
     if (!decision) throw gone()
     this.emit(userID, decision)
-    const option = decision.options.find((o) => o.id === choice.option)
-    const by = `(answered by the app “${label ?? app.party}”)`
-    const text = option ? `Decision ${id}: ${option.label} [${option.id}] ${by}${choice.text ? `\n${choice.text}` : ""}` : `Decision ${id}: ${choice.text} ${by}`
+    const text = answerText(decision, choice, `(answered by the app “${label ?? app.party}”)`)
     return { decision, ...(await this.replyTo(userID, decision, text, HUB_USER(userID))) }
   }
 
@@ -610,8 +716,29 @@ export class Decisions {
     return decision.state === "open" && this.now() >= decision.expiresAt ? { ...decision, state: "expired" } : decision
   }
 
-  private choice(decision: Decision, input: AnswerInput): { option?: string; text?: string } {
+  private choice(decision: Decision, input: AnswerInput): { option?: string; text?: string; picks?: Readonly<Record<string, string>> } {
     const text = input.text === undefined ? undefined : cleanText(input.text, ANSWER_MAX, "The answer text")
+    if (input.picks !== undefined && !decision.choices) throw invalid("This decision has no choices")
+    if (decision.choices) {
+      if (input.option !== undefined) throw invalid("This decision has choices: answer with picks")
+      // Text alone is the fallback of a console or device that knows no picks.
+      if (input.picks === undefined) {
+        if (text === undefined) throw invalid(`Pick an option for each of ${decision.choices.map((g) => g.id).join(", ")}`)
+        return { text }
+      }
+      const picks = input.picks as unknown
+      if (typeof picks !== "object" || picks === null || Array.isArray(picks)) throw invalid("picks must be {group: option}")
+      const given = picks as Record<string, unknown>
+      for (const key of Object.keys(given)) if (!decision.choices.some((g) => g.id === key)) throw invalid(`No choice group ${sanitizeLabel(key, 16)}`)
+      const out: Record<string, string> = {}
+      for (const group of decision.choices) {
+        const pick = given[group.id]
+        if (pick === undefined) throw invalid(`Pick an option for ${group.id}`)
+        if (typeof pick !== "string" || !group.options.some((o) => o.id === pick)) throw invalid(`Pick one of ${group.id}'s options: ${group.options.map((o) => o.id).join(", ")}`)
+        out[group.id] = pick
+      }
+      return { picks: out, ...(text === undefined ? {} : { text }) }
+    }
     if (!decision.options.length) {
       if (input.option !== undefined) throw invalid("This decision has no options: answer with text")
       if (text === undefined) throw invalid("This decision needs an answer text")

package/src/central/agent/delivery.ts

@@ -48,6 +48,7 @@
 //   answers, and nothing sent to an app raises a persistent depth.
 import type { DeliverRequest, DeliverResult, DeliveryMode, MessageKind as WireKind } from "../../protocol"
 import type { WakeSkip } from "../../../packages/sdk/src/types.ts"
+import type { ItemBudgets } from "../teams/budgets"
 import { isDeliverResult } from "../../protocol"
 import { randomBytes } from "node:crypto"
 import type { Clock, Counters, Locks, StateStore, Timers } from "../backend/types"
@@ -58,7 +59,7 @@ import { type Party, type PartyInfo, partyFromActor, partyKey, partyLabel, rende
 import { noticeOnly } from "../../../packages/sdk/src/envelope.ts"
 import { AgentError } from "./errors"
 import { type ExpiredReason, parseNotAfter } from "./not-after"
-import { HOP_CAP, HopTracker, MessageLimiter, type MessageLimits, overHopCap } from "./message-limits"
+import { HOP_ABSOLUTE_MAX, HOP_CAP, HopTracker, MessageLimiter, type MessageLimits } from "./message-limits"
 import { parseAddress } from "./names"
 import { type Delivery as DeliveryState, type Message, Messages, newMessageID } from "./messages"
 
@@ -115,6 +116,10 @@ export interface InboundPolicy {
 }
 
 export interface DeliveryDeps {
+  /** Item budgets are consulted only for shared-team exchanges, after the existing wake backstop admits. */
+  readonly itemBudgets?: Pick<ItemBudgets, "wake" | "current" | "currents" | "setCurrent" | "chargeChild">
+  /** Current team/item eligibility, shared by explicit sends and inherited replies. */
+  readonly items?: { eligible(userID: string, item: string, sessionIDs: readonly string[]): Promise<{ readonly ok: true; readonly teamID: string; readonly startedAt?: number; readonly parentItem?: string; readonly child?: boolean } | { readonly ok: false; readonly reason: "closed" | "archived" | "unseated"; readonly sessionID?: string; readonly team?: string }> }
   readonly state: StateStore
   readonly counters: Counters
   readonly registry: DeliveryRegistry
@@ -126,10 +131,23 @@ export interface DeliveryDeps {
   /** Labels of a session sender (default: its @name from the directory). */
   readonly describe?: (userID: string, sessionID: string) => PartyInfo
   readonly alert?: (userID: string, alert: DeliveryAlert) => void
+  /** The first over-cap message between two seats of a team, once per persistent chain. */
+  readonly teamHopCap?: (userID: string, input: { readonly teamID: string; readonly sender: string; readonly recipient: string; readonly limit: number }) => Promise<void>
+  /**
+   * (TA2-7) A message tagged with an item between two seats: true when that pair is looping on the item without
+   * progress, so the message is delivered without a wake (and charges no wake). Never throws through: a failure wakes.
+   */
+  readonly itemLoop?: (userID: string, input: { readonly teamID: string; readonly item: string; readonly from: string; readonly to: string }) => Promise<boolean>
+  /** A quiet, hub-authored note to the team's entry seat; never counts a message hop. */
+  readonly teamHopNotice?: (userID: string, teamID: string) => Promise<string | undefined>
   /** A pending message expired undelivered (its sender was told): the hub journals the change. Never throws through. */
   readonly expired?: (userID: string, message: Message) => void
   /** Limiter caps (default PAIR_LIMIT, USER_LIMIT, WAKE_BUDGET). */
   readonly limits?: Partial<MessageLimits>
+  /** Configured global agent-only wake hop limit (default 8; the live ceiling is AgentLimits', the bound HOP_ABSOLUTE_MAX). */
+  readonly hopLimit?: number
+  /** Latest hub-wide limit, consulted for every send and wake (console settings can change it live). */
+  readonly currentHopLimit?: () => number
   /** How long what an app received from a session raises its new messages (message-limits RELAY_WINDOW_MS). */
   readonly relayWindowMs?: number
   /** The users the re-wake loop looks at (every user of the hub; default: the users seen by this process since start). */
@@ -141,12 +159,14 @@ export interface DeliveryDeps {
   /** How often the re-wake loop runs (default REWAKE_TICK_MS). */
   readonly tickMs?: number
   /** Team communication policy (HWA-34, ../teams/policy.ts): team addresses and verdicts before anything is stored. */
-  readonly teams?: Pick<TeamPolicy, "prepare" | "answer">
+  readonly teams?: Pick<TeamPolicy, "prepare" | "answer" | "hopContext">
   /** (CON-04) Inbound policy per recipient session (the Concierge inbound rule), checked next to team policy. */
   readonly inbound?: InboundPolicy
 }
 
 export interface SendOptions {
+  /** Explicit team intake item, already authorized by the agent message route. */
+  readonly item?: string
   /** false: admit without starting a turn (reported queued). */
   readonly wake?: boolean
   /** Steer into a running turn, like an ask. */
@@ -173,6 +193,8 @@ export interface Sent {
   readonly woke?: boolean
   /** Why it was not (only when woke is false). */
   readonly wakeSkipped?: WakeSkip
+  /** Effective hop cap or wake budget, only with the corresponding wakeSkipped reason. */
+  readonly wakeLimit?: number
 }
 
 /** A reply or decline as sent, with the message it answered. */
@@ -273,6 +295,7 @@ export class Delivery {
   private readonly owner: string
 
   constructor(deps: DeliveryDeps) {
+    if (deps.hopLimit !== undefined && (!Number.isSafeInteger(deps.hopLimit) || deps.hopLimit < 1 || deps.hopLimit > HOP_ABSOLUTE_MAX)) throw new Error(`hopLimit must be 1–${HOP_ABSOLUTE_MAX}`)
     this.deps = deps
     const now = (this.now = deps.now ?? Date.now)
     this.timers = deps.timers ?? defaultTimers
@@ -314,7 +337,9 @@ export class Delivery {
     if (isUserAddress(addr)) return this.sendToUser(userID, actor, addr, kind, text, options)
     const from = this.party(userID, actor)
     const resolved = await this.resolveFor(userID, actor, from, addr, kind)
-    return this.sendTo(userID, from, addr, resolved, this.pick(resolved), kind, text, options)
+    const picked = this.pick(resolved)
+    const itemContext = await this.checkItem(userID, options.item, from, addr, [picked.sessionID])
+    return this.sendTo(userID, from, addr, resolved, picked, kind, text, options, itemContext)
   }
 
   /** Like send, to every session the address names (each role holder gets its own message). */
@@ -323,11 +348,22 @@ export class Delivery {
     if (isUserAddress(addr)) return [await this.sendToUser(userID, actor, addr, kind, text, options)]
     const from = this.party(userID, actor)
     const resolved = await this.resolveFor(userID, actor, from, addr, kind)
+    const itemContext = await this.checkItem(userID, options.item, from, addr, resolved.sessions.map((s) => s.sessionID))
     const sent: Sent[] = []
-    for (const entry of resolved.sessions) sent.push(await this.sendTo(userID, from, addr, resolved, entry, kind, text, options))
+    for (const entry of resolved.sessions) sent.push(await this.sendTo(userID, from, addr, resolved, entry, kind, text, options, itemContext))
     return sent
   }
 
+  private async checkItem(userID: string, item: string | undefined, from: Party, addr: string, recipients: readonly string[]): Promise<{ teamID: string; startedAt?: number; parentItem?: string; child?: boolean } | undefined> {
+    if (item === undefined) return undefined
+    if (from.kind !== "session" || !this.deps.items) throw new AgentError("invalid", "item applies to messages between team members")
+    const result = await this.deps.items.eligible(userID, item, [from.sessionID, ...recipients])
+    if (result.ok) return { teamID: result.teamID, ...(result.startedAt !== undefined ? { startedAt: result.startedAt } : {}), ...(result.parentItem ? { parentItem: result.parentItem } : {}), ...(result.child ? { child: true } : {}) }
+    if (result.reason === "closed") throw new AgentError("invalid", `item ${item} is closed`)
+    if (result.reason === "archived") throw new AgentError("invalid", `team ${result.team ?? "of this item"} is archived`)
+    throw new AgentError("invalid", `the sender and every recipient of ${addr} must be seated in item ${item}'s team`)
+  }
+
   /** A notAfter validated against this engine's clock (parseNotAfter): throws invalid or expired. */
   checkNotAfter(value: unknown): number | undefined {
     return parseNotAfter(value, this.now())
@@ -348,6 +384,30 @@ export class Delivery {
     return this.hops.humanTurn(userID, sessionID)
   }
 
+  /** A quiet hub notice (never a wake, never a hop) to the team's entry seat; false when the team has none. */
+  async notifyTeamEntry(userID: string, teamID: string, text: string): Promise<boolean> {
+    const entry = await this.deps.teamHopNotice?.(userID, teamID)
+    if (!entry) return false
+    const id = this.newID()
+    await this.request(userID, entry, {
+      op: "deliver", sessionID: entry, messageID: id, wake: false,
+      text: `[hub] notice · ${text} · ${id}`,
+      meta: { kind: "msg", from: "hub", to: entry, delivery: "queue" },
+    })
+    return true
+  }
+
+  async notifyTeamHopCap(userID: string, teamID: string, decisionID: string): Promise<void> {
+    const entry = await this.deps.teamHopNotice?.(userID, teamID)
+    if (!entry) return
+    const id = this.newID()
+    await this.request(userID, entry, {
+      op: "deliver", sessionID: entry, messageID: id, wake: false,
+      text: `[hub] notice · Team messages reached the hop cap. The user has a Renew Decision ${decisionID}; wait for their choice. · ${id}`,
+      meta: { kind: "msg", from: "hub", to: entry, delivery: "queue" },
+    })
+  }
+
   /** Delivers the user's pending messages whose sessions a deliver-capable spoke reports now, oldest first. */
   /** Delivers the user's pending messages (only `sessionID`'s when given); flushes run one at a time per user. */
   flush(userID: string, sessionID?: string): Promise<void> {
@@ -466,7 +526,7 @@ export class Delivery {
     return { message }
   }
 
-  private async sendTo(userID: string, from: Party, addr: string, resolved: Resolved, entry: DirectoryEntry, kind: "msg" | "ask", text: string, options: SendOptions): Promise<Sent> {
+  private async sendTo(userID: string, from: Party, addr: string, resolved: Resolved, entry: DirectoryEntry, kind: "msg" | "ask", text: string, options: SendOptions, itemContext?: { teamID: string; startedAt?: number; parentItem?: string; child?: boolean }): Promise<Sent> {
     const sessionID = entry.sessionID
     const recipient: Party = { kind: "session", sessionID, ...(entry.name ? { name: entry.name } : {}) }
     await this.deps.inbound?.outbound?.(userID, from, kind)
@@ -475,6 +535,19 @@ export class Delivery {
     await this.limiter.admit(userID, from, recipient)
     const hop = Math.max(await this.hops.next(userID, from, { to: recipient }), options.chainHop ?? 0)
     const generation = resolved.address.kind === "role" && !("team" in resolved) ? roleGeneration(entry, resolved.address) : undefined
+    // Try the sender's latest received/assigned item across teams, not just the default shared hop team:
+    // a session may be seated in A and B while its current work belongs to B.
+    if (!options.item && from.kind === "session" && this.deps.itemBudgets && this.deps.items) {
+      for (const candidate of await this.deps.itemBudgets.currents(userID, from.sessionID)) {
+        try {
+          const eligible = await this.deps.items.eligible(userID, candidate.item, [from.sessionID, sessionID])
+          if (!eligible.ok || eligible.teamID !== candidate.teamID) continue
+          itemContext = { teamID: eligible.teamID, ...(eligible.startedAt !== undefined ? { startedAt: eligible.startedAt } : {}), ...(eligible.parentItem ? { parentItem: eligible.parentItem } : {}), ...(eligible.child ? { child: true } : {}) }
+          options = { ...options, item: candidate.item }
+          break
+        } catch (cause) { console.error("[hub] sender item context lookup failed:", cause) }
+      }
+    }
     const message = await this.messages.send(userID, {
       from,
       to: addr,
@@ -482,6 +555,7 @@ export class Delivery {
       kind,
       text,
       hop,
+      ...(options.item ? { item: options.item } : {}),
       ...(generation === undefined ? {} : { generation }),
       ...(options.expiresInMs === undefined ? {} : { expiresInMs: options.expiresInMs }),
       ...(options.notAfter === undefined ? {} : { notAfter: options.notAfter }),
@@ -489,12 +563,22 @@ export class Delivery {
     await this.hops.received(userID, recipient, hop, from)
     this.users.add(userID)
     const unwanted: WakeSkip | undefined = options.wake === false ? "wake_false" : entry.parentID !== undefined ? "subagent" : undefined
-    const skipped = await this.wakeFor(userID, message, unwanted)
-    if (kind === "ask" && unwanted === undefined && !overHopCap(hop)) {
+    const team = "team" in resolved ? resolved.team : undefined
+    const explicitTeamID = typeof team === "object" && team !== null && "teamID" in team && typeof team.teamID === "string" ? team.teamID : undefined
+    const context = await this.deps.teams?.hopContext(userID, from, recipient, explicitTeamID ?? itemContext?.teamID)
+    if (context && itemContext?.teamID === context.teamID && this.deps.itemBudgets && message.item) {
+      await this.deps.itemBudgets.setCurrent(userID, context.teamID, sessionID, message.item)
+        .catch((cause) => console.error("[hub] item context write failed:", cause))
+    }
+    const global = this.deps.currentHopLimit?.() ?? this.deps.hopLimit ?? HOP_CAP
+    const limit = Math.min(context?.limit ?? global, global)
+    const skip = await this.wakeFor(userID, message, unwanted, limit, context?.teamID, itemContext?.teamID === context?.teamID ? itemContext : undefined)
+    const skipped = skip.reason
+    if (kind === "ask" && unwanted === undefined && hop <= limit) {
       const rewake: Rewake = { messageID: message.id, sessionID, reminders: 0, nextAt: message.at + backoff(0) }
       await this.deps.state.put(userID, REWAKE, message.id, rewake)
     }
-    return this.deliver(userID, message, sessionID, skipped, options.urgent === true)
+    return this.deliver(userID, message, sessionID, skipped, options.urgent === true, skip.wakeLimit ?? (skipped === "hop_cap" ? limit : skipped === "budget" ? this.limiter.wakeLimit : undefined))
   }
 
   private schedule(): void {
@@ -589,7 +673,7 @@ export class Delivery {
     replyTo: string,
     options: SendOptions,
     kind: "reply" | "decline",
-    store: (input: { from: Party; replyTo: string; hop: number; generation?: number }) => Promise<{ message: Message; original: Message }>,
+    store: (input: { from: Party; replyTo: string; hop: number; generation?: number; item?: string }) => Promise<{ message: Message; original: Message }>,
   ): Promise<Replied> {
     const from = this.party(userID, actor)
     const original = await this.messages.get(userID, replyTo)
@@ -605,36 +689,94 @@ export class Delivery {
     if (to) await this.limiter.admit(userID, from, to)
     const hop = await this.hops.next(userID, from, original ? { answering: original, ...(to ? { to } : {}) } : {})
     const generation = original && actor.kind === "session" ? this.holderGeneration(userID, actor.sessionID, original) : undefined
-    const answered = await store({ from, replyTo, hop, ...(generation === undefined ? {} : { generation }) })
+    let item: string | undefined
+    let itemContext: { teamID: string; startedAt?: number; parentItem?: string; child?: boolean } | undefined
+    if (original?.item && from.kind === "session" && to?.kind === "session") {
+      try {
+        const eligible = await this.deps.items?.eligible(userID, original.item, [from.sessionID, to.sessionID])
+        if (eligible?.ok) { item = original.item; itemContext = { teamID: eligible.teamID, ...(eligible.startedAt !== undefined ? { startedAt: eligible.startedAt } : {}), ...(eligible.parentItem ? { parentItem: eligible.parentItem } : {}), ...(eligible.child ? { child: true } : {}) } }
+      } catch (cause) {
+        // A reply must still be delivered; uncertainty about item attribution fails closed (no item).
+        console.error("[hub] reply item eligibility failed:", cause)
+      }
+    }
+    const answered = await store({ from, replyTo, hop, ...(generation === undefined ? {} : { generation }), ...(item ? { item } : {}) })
     const { message } = answered
     await this.hops.received(userID, message.recipient, hop, from)
     this.users.add(userID)
     if (message.recipient.kind !== "session") return answered
     const sessionID = message.recipient.sessionID
     const unwanted: WakeSkip | undefined = options.wake === false ? "wake_false" : this.isSubagent(userID, sessionID) ? "subagent" : undefined
-    const skipped = await this.wakeFor(userID, message, unwanted)
-    return { ...(await this.deliver(userID, message, sessionID, skipped, true)), original: answered.original }
+    const context = await this.deps.teams?.hopContext(userID, from, message.recipient, itemContext?.teamID)
+    if (context && itemContext?.teamID === context.teamID && this.deps.itemBudgets && message.item) {
+      await this.deps.itemBudgets.setCurrent(userID, context.teamID, sessionID, message.item)
+        .catch((cause) => console.error("[hub] item context write failed:", cause))
+    }
+    const global = this.deps.currentHopLimit?.() ?? this.deps.hopLimit ?? HOP_CAP
+    const limit = Math.min(context?.limit ?? global, global)
+    const skip = await this.wakeFor(userID, message, unwanted, limit, context?.teamID, itemContext?.teamID === context?.teamID ? itemContext : undefined)
+    const skipped = skip.reason
+    return { ...(await this.deliver(userID, message, sessionID, skipped, true, skip.wakeLimit ?? (skipped === "hop_cap" ? limit : skipped === "budget" ? this.limiter.wakeLimit : undefined))), original: answered.original }
   }
 
   /**
    * Why the message may not start a turn (undefined: it may): `unwanted` (wake:false or a subagent recipient), over
    * the hop cap (alerting once at the cap), or no wake budget left.
    */
-  private async wakeFor(userID: string, message: Message, unwanted: WakeSkip | undefined): Promise<WakeSkip | undefined> {
-    if (unwanted) return unwanted
-    if (message.recipient.kind !== "session") return "wake_false"
-    if (overHopCap(message.hop)) {
-      if (message.hop === HOP_CAP + 1) {
+  private async wakeFor(userID: string, message: Message, unwanted: WakeSkip | undefined, limit = this.deps.currentHopLimit?.() ?? this.deps.hopLimit ?? HOP_CAP, teamID?: string, itemContext?: { teamID: string; startedAt?: number; parentItem?: string; child?: boolean }): Promise<{ reason?: WakeSkip; wakeLimit?: number }> {
+    if (unwanted) return { reason: unwanted }
+    if (message.recipient.kind !== "session") return { reason: "wake_false" }
+    if (message.hop > limit) {
+      if (teamID && message.from.kind === "session") {
+        try {
+          await this.deps.teamHopCap?.(userID, { teamID, sender: message.from.sessionID, recipient: message.recipient.sessionID, limit })
+        } catch (cause) {
+          // The message has already been stored. A failed Decision must not prevent delivery or wake it.
+          console.error(`[hub] team hop-cap alert failed: ${cause instanceof Error ? cause.message : String(cause)}`)
+        }
+      } else if (message.hop === limit + 1) {
         this.deps.alert?.(userID, {
           kind: "hopCap",
           sessionID: message.recipient.sessionID,
           messageID: message.id,
-          text: `Agent messages went ${HOP_CAP} hops without you (latest: ${partyLabel(message.from)} → ${partyLabel(message.recipient)}); further messages in this chain no longer wake anyone`,
+          text: `Agent messages went ${limit} hops without you (latest: ${partyLabel(message.from)} → ${partyLabel(message.recipient)}); further messages in this chain no longer wake anyone`,
         })
       }
-      return "hop_cap"
+      return { reason: "hop_cap" }
+    }
+    if (teamID && itemContext?.teamID === teamID && message.item && message.from.kind === "session" && this.deps.itemLoop) {
+      let looping = false
+      try { looping = await this.deps.itemLoop(userID, { teamID, item: message.item, from: message.from.sessionID, to: message.recipient.sessionID }) }
+      catch (cause) { console.error("[hub] item loop check failed:", cause) }
+      if (looping) return { reason: "item_loop" }
+    }
+    if (!(await this.limiter.wake(userID, message.recipient))) return { reason: "budget" }
+    if (teamID && this.deps.itemBudgets) {
+      // A wake is the hub deciding to wake: do not refund for a later spoke failure or offline pending delivery.
+      let chargedItem = itemContext && message.item ? (itemContext.child ? itemContext.parentItem : message.item) : undefined
+      let chargedStartedAt = chargedItem === message.item ? itemContext?.startedAt : undefined
+      if (chargedItem && itemContext?.parentItem) {
+        try {
+          const root = message.from.kind === "session" && message.recipient.kind === "session" ? await this.deps.items?.eligible(userID, chargedItem, [message.from.sessionID, message.recipient.sessionID]) : undefined
+          if (!root?.ok || root.child || root.teamID !== teamID) chargedItem = undefined
+          else chargedStartedAt = root.startedAt
+        } catch (cause) { console.error("[hub] parent item eligibility failed:", cause); chargedItem = undefined }
+      }
+      let budget: Awaited<ReturnType<ItemBudgets["wake"]>>
+      const seats = message.from.kind === "session" ? [message.from.sessionID, message.recipient.sessionID] : [message.recipient.sessionID]
+      try { budget = await this.deps.itemBudgets.wake(userID, teamID, chargedItem, chargedStartedAt, seats) }
+      catch (cause) {
+        // The message is stored already. A failed budget read/write must never turn it into a send error or a wake.
+        console.error("[hub] item budget charge failed; skipping wake:", cause)
+        return { reason: "item_budget" }
+      }
+      if (budget.allowed && itemContext?.child && message.item) {
+        try { await this.deps.itemBudgets.chargeChild(userID, teamID, message.item, chargedItem ?? "pool") }
+        catch (cause) { console.error("[hub] child item usage failed:", cause) }
+      }
+      if (!budget.allowed) return { reason: "item_budget", ...(budget.reason === "wakes" ? { wakeLimit: budget.limit } : {}) }
     }
-    return (await this.limiter.wake(userID, message.recipient)) ? undefined : "budget"
+    return {}
   }
 
   /** The replier's generation of the role the original reached (undefined: not a role, or not held now). */
@@ -672,9 +814,9 @@ export class Delivery {
   }
 
   /** Delivers now, or queues the message as pending when no spoke takes it. */
-  private async deliver(userID: string, message: Message, sessionID: string, skipped: WakeSkip | undefined, urgent: boolean): Promise<Sent> {
+  private async deliver(userID: string, message: Message, sessionID: string, skipped: WakeSkip | undefined, urgent: boolean, wakeLimit?: number): Promise<Sent> {
     const wake = skipped === undefined
-    const woke = wake ? { woke: true } : { woke: false, wakeSkipped: skipped }
+    const woke = wake ? { woke: true } : { woke: false, wakeSkipped: skipped, ...(wakeLimit !== undefined ? { wakeLimit } : {}) }
     // Messages still pending for this session go first (e.g. a quiet one a busy spoke refused, RF-05): the turn this
     // one starts then carries them, instead of them arriving inside it.
     if (wake && (await this.deps.state.list<Pending>(userID, PENDING)).some((p) => p.value.sessionID === sessionID)) await this.flush(userID, sessionID)

package/src/central/agent/errors.ts

@@ -1,5 +1,6 @@
 // The /api/agent error envelope (design §8, §14.5): {error: {code, message, hint?, ...extra}}. Only /api/agent/*
-// answers this way; the console routes keep their {error: string, code?} envelope (the web app reads it).
+// answers this way; the console routes keep their {error: string, code?} envelope (the web app reads it), which
+// is rewritten to this one under /api/v1 only (../api-v1.ts).
 
 /** HTTP status of each agent error code. */
 export const AGENT_ERROR_STATUS = {

package/src/central/agent/events.ts

@@ -244,9 +244,18 @@ export function roleEvent(sessionID: string, held: boolean, role: { role: string
   }
 }
 
+/**
+ * (SS-1) Whether a session.changed is a change of state, not of health alone (state === prev). Before health fields,
+ * every session.changed was a state change; consumers that mean "went into state X" check this.
+ */
+export const stateChanged = (data: Readonly<Record<string, unknown>> | undefined): boolean => data?.prev === undefined || data.prev !== data.state
+
 interface Known {
   state: string
   blockers: Set<string>
+  /** (SS-1) The health kind and quota reset last journaled (undefined: ok). */
+  healthKind?: string
+  healthResetAt?: number
 }
 
 /**
@@ -266,8 +275,17 @@ export class StatusDiff {
       const open = new Set(entry.blockers.map((b) => b.id))
       for (const b of entry.blockers) if (!known?.blockers.has(b.id)) out.push({ type: "blocker.opened", family: "session", subject, data: { blockerID: b.id, kind: b.kind } })
       for (const id of known?.blockers ?? []) if (!open.has(id)) out.push({ type: "blocker.closed", family: "session", subject, data: { blockerID: id } })
-      if (known?.state !== entry.state) out.push({ type: "session.changed", family: "session", subject, data: { state: entry.state, ...(known ? { prev: known.state } : {}) } })
-      after.set(entry.id, { state: entry.state, blockers: open })
+      // (SS-1) Flat health fields (the journal's data is flat): healthKind while not ok and once as "ok" on recovery,
+      // healthResetAt for a quota; a change of health alone is a session.changed too. Never the provider's text.
+      const health = (entry as { health?: { kind: string; resetAt?: number } }).health
+      const healthKind = health && health.kind !== "ok" ? health.kind : undefined
+      const healthResetAt = healthKind !== undefined ? health!.resetAt : undefined
+      const healthChanged = known?.healthKind !== healthKind || known?.healthResetAt !== healthResetAt
+      if (known?.state !== entry.state || healthChanged) {
+        const healthData = healthKind !== undefined ? { healthKind, ...(healthResetAt !== undefined ? { healthResetAt } : {}) } : known?.healthKind !== undefined ? { healthKind: "ok" } : {}
+        out.push({ type: "session.changed", family: "session", subject, data: { state: entry.state, ...(known ? { prev: known.state } : {}), ...healthData } })
+      }
+      after.set(entry.id, { state: entry.state, blockers: open, ...(healthKind !== undefined ? { healthKind } : {}), ...(healthResetAt !== undefined ? { healthResetAt } : {}) })
     }
     this.trees.set(rootID, after)
     return out