@huynle/hub 0.10.1 → 0.11.1

package/packages/sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-sdk",
-  "version": "0.10.1",
+  "version": "0.11.1",
   "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/app-front.ts

@@ -383,8 +383,8 @@ export interface AppConversation {
 export interface AppDecisions {
   /** The Decisions this app may answer (`state: "open"` for the waiting ones), newest first. */
   list(options?: Signal & { readonly state?: DecisionState }): Promise<{ decisions: Decision[] }>
-  /** Answers one with a once-off option or text; the first answer wins (410 gone after). */
-  answer(id: string, answer: Signal & { readonly option?: string; readonly text?: string }): Promise<DecisionAnswered>
+  /** Answers one with a once-off option, picks (one option per choice group) or text; the first answer wins (410 gone after). */
+  answer(id: string, answer: Signal & { readonly option?: string; readonly text?: string; readonly picks?: Readonly<Record<string, string>> }): Promise<DecisionAnswered>
 }
 
 export function speechApi(hub: AppFrontTransport): AppSpeech {

package/packages/sdk/src/ask-fields.ts

@@ -0,0 +1,76 @@
+// (DC-4) The Decision fields an agent tool sends with an ask to @me (the OpenCode hub tool, the MCP ask tool): their
+// JSON Schema properties and a shape check of a tool call's arguments. The hub validates the values (ids, sizes,
+// one recommendation per group, choices xor options; non-@me asks are 400); this only refuses wrong types early.
+import type { AskOptions } from "./client.ts"
+import type { DecisionKind, DecisionTier, DecisionUrgency } from "./types.ts"
+
+const URGENCIES: readonly DecisionUrgency[] = ["low", "normal", "high"]
+const TIERS: readonly DecisionTier[] = ["confirm", "tap"]
+const KINDS: readonly DecisionKind[] = ["question", "plan", "merge", "release"]
+
+/** JSON Schema properties of the ask @me Decision fields. */
+export const DECISION_ASK_PROPERTIES = {
+  options: {
+    type: "array",
+    items: { type: "object", properties: { id: { type: "string" }, label: { type: "string" }, safe: { type: "boolean" } }, required: ["id", "label"] },
+    description: "ask @me: buttons the user taps, [{id, label, safe?}] (at most 8; id: lowercase letters, digits, - or _).",
+  },
+  recommendation: {
+    type: "object",
+    properties: { option: { type: "string" }, why: { type: "string" } },
+    required: ["option"],
+    description: "ask @me: the option you recommend ({option: an option id, why}).",
+  },
+  urgency: { type: "string", enum: [...URGENCIES], description: "ask @me: low, normal (default) or high." },
+  tier: { type: "string", enum: [...TIERS], description: "ask @me: confirm (default: any of the user's devices) or tap (only the signed-in console)." },
+  kind: { type: "string", enum: [...KINDS], description: "ask @me: what it is about: question (default), plan, merge or release." },
+  choices: {
+    type: "array",
+    items: {
+      type: "object",
+      properties: {
+        id: { type: "string" },
+        label: { type: "string" },
+        options: { type: "array", items: { type: "object", properties: { id: { type: "string" }, label: { type: "string" }, recommended: { type: "boolean" } }, required: ["id", "label"] } },
+      },
+      required: ["id", "label", "options"],
+    },
+    description: 'ask @me: several points in one ask, instead of options: [{id: "D1", label, options: [{id, label, recommended?}]}], 1–12 groups of 2–6 options, at most one recommended each; the user picks one option per group and you get one "D1: label [a]" line per group.',
+  },
+} as const
+
+export const DECISION_ASK_FIELDS = Object.keys(DECISION_ASK_PROPERTIES) as readonly (keyof typeof DECISION_ASK_PROPERTIES)[]
+
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+
+/**
+ * The Decision fields of a tool call's arguments (only those given), shape-checked. Throws an Error naming the field
+ * for a wrong type; the hub checks the values.
+ */
+export function decisionAskFields(args: Readonly<Record<string, unknown>>): Partial<AskOptions> {
+  const out: Record<string, unknown> = {}
+  const { options, recommendation, urgency, tier, kind, choices } = args
+  const objects = (value: unknown, field: string, shape: string) => {
+    if (!Array.isArray(value) || !value.every(isObject)) throw new Error(`"${field}" must be a list of ${shape}`)
+    return value
+  }
+  if (options !== undefined) out.options = objects(options, "options", "{id, label, safe?}")
+  if (recommendation !== undefined) {
+    if (!isObject(recommendation) || typeof recommendation.option !== "string") throw new Error(`"recommendation" must be {option, why?}`)
+    out.recommendation = recommendation
+  }
+  const oneOf = (value: unknown, field: string, allowed: readonly string[]) => {
+    if (value === undefined) return
+    if (typeof value !== "string" || !allowed.includes(value)) throw new Error(`"${field}" is one of ${allowed.join(", ")}`)
+    out[field] = value
+  }
+  oneOf(urgency, "urgency", URGENCIES)
+  oneOf(tier, "tier", TIERS)
+  oneOf(kind, "kind", KINDS)
+  if (choices !== undefined) {
+    const shape = "{id, label, options: [{id, label, recommended?}]}"
+    for (const group of objects(choices, "choices", shape)) objects(group.options, "choices", shape)
+    out.choices = choices
+  }
+  return out as Partial<AskOptions>
+}

package/packages/sdk/src/client.ts

@@ -16,6 +16,8 @@ import type {
   CreatedAppToken,
   Decision,
   DecisionAnswered,
+  DecisionChoice,
+  DecisionKind,
   DecisionOption,
   DecisionState,
   DecisionTier,
@@ -287,6 +289,8 @@ export interface RoleOptions extends TargetOptions {
 }
 
 export interface MsgOptions extends CallOptions {
+  /** Explicit team intake item (itk_ ID), allowed only to a currently seated session. */
+  readonly item?: string
   /** false: admit without starting a turn. */
   readonly wake?: boolean
   /** Steer into a running turn. */
@@ -319,12 +323,16 @@ export interface AskOptions extends MsgOptions {
   readonly onTimeout?: string
   /** Addresses of the sessions it concerns. */
   readonly about?: readonly string[]
+  /** (DC-1) Structured choices instead of options: the user picks one option in each group (1–12 groups of 2–6). */
+  readonly choices?: readonly DecisionChoice[]
+  /** (DC-1) What it is about (default question). */
+  readonly kind?: DecisionKind
 }
 
 /** The Decision fields of AskOptions, when given. */
 const decisionFields = (options: AskOptions) => {
   const out: Record<string, unknown> = {}
-  for (const key of ["options", "recommendation", "urgency", "tier", "deadline", "onTimeout", "about"] as const) if (options[key] !== undefined) out[key] = options[key]
+  for (const key of ["options", "recommendation", "choices", "kind", "urgency", "tier", "deadline", "onTimeout", "about"] as const) if (options[key] !== undefined) out[key] = options[key]
   return out
 }
 
@@ -355,6 +363,7 @@ const signalOf = (options: CallOptions) => (options.signal ? { signal: options.s
 const idempotent = (options: IdempotentOptions) => ({ ...signalOf(options), ...(options.idempotencyKey ? { headers: { "idempotency-key": options.idempotencyKey } } : {}) })
 /** The wake and urgent fields of a send, when given. */
 const sendFields = (options: MsgOptions) => ({
+  ...(options.item !== undefined ? { item: options.item } : {}),
   ...(options.wake !== undefined ? { wake: options.wake } : {}),
   ...(options.urgent !== undefined ? { urgent: options.urgent } : {}),
   ...(options.notAfter !== undefined ? { notAfter: options.notAfter } : {}),
@@ -727,7 +736,7 @@ export class HubClient {
   }
 
   /** Answers a Decision as the user (a device token; tap Decisions need the console): first answer wins, later ones are gone. */
-  answerDecision(id: string, answer: CallOptions & { readonly option?: string; readonly text?: string }): Promise<DecisionAnswered> {
+  answerDecision(id: string, answer: CallOptions & { readonly option?: string; readonly text?: string; readonly picks?: Readonly<Record<string, string>> }): Promise<DecisionAnswered> {
     const { signal: _signal, ...body } = answer
     return this.call("POST", `/api/decisions/${segment(id)}/answer`, { body, ...signalOf(answer) })
   }
@@ -780,6 +789,19 @@ export class HubClient {
     return this.call("GET", `${AGENT}/grants`, signalOf(options))
   }
 
+  /** Grants held by this session/app; a user credential has no holder. */
+  heldGrants(options: CallOptions = {}): Promise<{ grants: Grant[] }> {
+    return this.call("GET", `${AGENT}/grants/mine`, signalOf(options))
+  }
+
+  heldGrant(id: string, options: CallOptions = {}): Promise<{ grant: Grant }> {
+    return this.call("GET", `${AGENT}/grants/mine/${segment(id)}`, signalOf(options))
+  }
+
+  revokeHeldGrant(id: string, options: CallOptions = {}): Promise<{ grant: Grant }> {
+    return this.call("DELETE", `${AGENT}/grants/mine/${segment(id)}`, signalOf(options))
+  }
+
   grant(id: string, options: CallOptions = {}): Promise<{ grant: Grant }> {
     return this.call("GET", `${AGENT}/grants/${segment(id)}`, signalOf(options))
   }

package/packages/sdk/src/envelope.ts

@@ -35,9 +35,10 @@ const ANSI =
 /**
  * C0 except tab/newline, DEL, C1, Arabic letter mark, zero-width and directional marks (U+200B-200F), line and
  * paragraph separators and bidi embeddings/overrides (U+2028-202E), word joiner, invisible operators and bidi
- * isolates (U+2060-206F), BOM.
+ * isolates (U+2060-206F), BOM, and every other format character (\p{Cf}: soft hyphen, Unicode TAG characters
+ * U+E0000-E007F, …).
  */
-const CONTROL = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f\u061c\u200b-\u200f\u2028-\u202e\u2060-\u206f\ufeff]/g
+const CONTROL = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f\u061c\u200b-\u200f\u2028-\u202e\u2060-\u206f\ufeff\p{Cf}]/gu
 
 /** Message text: newlines normalised, escape sequences and invisible/control characters removed. */
 export function sanitizeText(text: string): string {

package/packages/sdk/src/index.ts

@@ -2,6 +2,7 @@
 // errors (HubError, HubTransportError), the answer types, the SSE parser of the watch stream, and the pure
 // envelope renderer/sanitiser and address parser shared with the hub, launches, and webhook verification.
 export * from "./address.ts"
+export * from "./ask-fields.ts"
 export * from "./app-front.ts"
 export * from "./artifacts.ts"
 export * from "./artifact-jobs.ts"

package/packages/sdk/src/team-intake.ts

@@ -41,6 +41,12 @@ export interface TeamIntake {
   readonly lastError?: string
   readonly updatedAt: number
   readonly routedAt?: number
+  /** First active work (routed or in progress); blocked time still counts. */
+  readonly startedAt?: number
+  /** Session-submitted child; its budget is charged to this root item. */
+  readonly parentItem?: string
+  /** Per-item usage at the time of this read (hubs with team item budgets). */
+  readonly usage?: { readonly wakes: number; readonly hours: number; readonly generation: number; readonly budget: { readonly wakes: number; readonly hours: number }; readonly chargedTo?: string }
   readonly closedAt?: number
 }
 

package/packages/sdk/src/teams.ts

@@ -53,6 +53,9 @@ export interface TeamSpec {
   readonly title: string
   readonly description?: string
   readonly mode: TeamMode
+  readonly hopLimit?: number
+  readonly itemBudget?: { readonly wakes: number; readonly hours: number }
+  readonly loop?: { readonly messages: number; readonly windowMinutes: number }
   readonly roles: readonly TeamRole[]
   /** The intake role (e.g. the project manager): receives submitted work and supervises members. */
   readonly entryRole: string
@@ -149,6 +152,7 @@ export interface TeamWorkspaceLink {
 export interface TeamRosterSeat {
   readonly staffing: TeamStaffing
   readonly presence: TeamSessionPresence
+  readonly stalled?: "hop cap"
   readonly memberID?: string
   readonly supervisorMemberID?: string
   readonly profile?: {

package/packages/sdk/src/types.ts

@@ -43,6 +43,8 @@ export interface SessionView {
   readonly harness?: string
   readonly parentID?: string
   readonly busySince?: number
+  /** (SS-1, hub ≥ this release) Why the session is not making progress; absent: ok (or an older hub). */
+  readonly health?: SessionHealth
   readonly now?: string
   readonly blockers?: readonly Blocker[]
   readonly children?: number
@@ -54,6 +56,18 @@ export interface SessionView {
   readonly intent?: IntentField
 }
 
+/**
+ * (SS-1) A session's health next to its state (a session retrying a provider request stays "working"). Kinds a client
+ * does not know should be shown as-is. `detail` is the provider's message, sanitised (≤ 200 characters).
+ */
+export interface SessionHealth {
+  readonly kind: "ok" | "retrying" | "stalled" | "quota" | "auth" | "model_unavailable" | "context_overflow" | "network" | "failed" | (string & {})
+  readonly since?: number
+  readonly resetAt?: number
+  readonly attempt?: number
+  readonly detail?: string
+}
+
 /** (CON-02) Who set a session's intent, highest precedence first. */
 export type IntentSource = "user" | "launch" | "self" | "prompt" | "title"
 
@@ -291,6 +305,8 @@ export interface AgentMessage {
   /** The role holder generation it reached (role addresses). */
   readonly generation?: number
   readonly text: string
+  /** The explicitly attributed team intake item (when the sender supplied one). */
+  readonly item?: string
   readonly replyTo?: string
   readonly state: MessageState
   readonly at: number
@@ -308,10 +324,11 @@ export interface AgentMessage {
 
 /**
  * Why a message to a session did not start a turn: the sender asked wake:false, the recipient is a subagent
- * (never woken), the reply chain went past the hop cap (8 hops without a human turn), or the recipient's wake
- * budget (30 per 10 minutes) is spent. The message is still delivered.
+ * (never woken), the reply chain passed the hub's effective hop cap (agents.hopLimit under Settings → Admin,
+ * optionally narrowed by the team), or the recipient's wake budget was spent.
+ * The message is still delivered; wakeLimit carries the effective cap or budget when the hub knows it.
  */
-export type WakeSkip = "wake_false" | "subagent" | "hop_cap" | "budget"
+export type WakeSkip = "wake_false" | "subagent" | "hop_cap" | "budget" | "item_budget" | "item_loop"
 
 /** POST /api/agent/msg and /ask: the stored message and how it was delivered (none: stored only). */
 export interface Sent {
@@ -321,6 +338,8 @@ export interface Sent {
   readonly woke?: boolean
   /** When woke is false: why. */
   readonly wakeSkipped?: WakeSkip
+  /** Effective hop cap or per-10-minute wake budget, with wakeSkipped hop_cap or budget (absent on older hubs). */
+  readonly wakeLimit?: number
 }
 
 /** POST /api/agent/msg or /ask with all: one per session. */
@@ -342,6 +361,17 @@ export interface DecisionOption {
   readonly safe?: boolean
 }
 
+/** (DC-1) One point of a structured ask: the user picks one of its 2–6 options (at most one recommended). */
+export interface DecisionChoice {
+  /** 1–8 letters, digits, - or _ (e.g. D1). */
+  readonly id: string
+  readonly label: string
+  readonly options: readonly { readonly id: string; readonly label: string; readonly recommended?: boolean }[]
+}
+
+/** (DC-1) What an ask is about (absent: a question). */
+export type DecisionKind = "question" | "plan" | "merge" | "release"
+
 export type DecisionUrgency = "low" | "normal" | "high"
 /** confirm: any of the user's devices; tap: only the signed-in console. */
 export type DecisionTier = "confirm" | "tap"
@@ -360,6 +390,8 @@ export interface Decision {
   readonly question: string
   readonly options: readonly DecisionOption[]
   readonly recommendation?: { readonly option: string; readonly why?: string }
+  readonly choices?: readonly DecisionChoice[]
+  readonly kind?: DecisionKind
   readonly urgency: DecisionUrgency
   readonly tier: DecisionTier
   readonly deadline?: number
@@ -369,7 +401,7 @@ export interface Decision {
   readonly expiresAt: number
   readonly escalatedAt?: number
   /** answeredBy "app": an app answered it (`app`: its party `app:<id>`, `appLabel`: its label then). */
-  readonly answer?: { readonly option?: string; readonly text?: string; readonly answeredBy: "user" | "timeout" | "app"; readonly at: number; readonly deviceID?: string; readonly app?: string; readonly appLabel?: string }
+  readonly answer?: { readonly option?: string; readonly picks?: Readonly<Record<string, string>>; readonly text?: string; readonly via?: "voice" | "text"; readonly answeredBy: "user" | "timeout" | "app"; readonly at: number; readonly deviceID?: string; readonly app?: string; readonly appLabel?: string }
   /** Why it closed without an answer (state closed). */
   readonly closed?: { readonly at: number; readonly reason: string }
 }

package/packages/sdk/src/wake.ts

@@ -6,15 +6,20 @@ import type { Sent, WakeSkip } from "./types.ts"
 export const WAKE_SKIP_TEXT: Readonly<Record<WakeSkip, string>> = {
   wake_false: "sent without a wake",
   subagent: "subagents are never woken",
-  hop_cap: "hop limit reached (8 agent messages without a human turn)",
-  budget: "wake budget spent (30 per 10 minutes)",
+  hop_cap: "hop limit reached (too many agent messages without a human turn)",
+  budget: "wake budget spent",
+  item_budget: "item wake budget spent",
+  item_loop: "this pair is looping on the item without progress; the user decides",
 }
 
 /**
  * ` — wake skipped: <reason>` when the hub did not wake the recipient and the message waits for a later turn; empty
  * when it woke, went into a running turn (steer) or started one, or the hub did not say (hubs before 0.8.1).
  */
-export function wakeSkipNote({ delivery, woke, wakeSkipped }: Pick<Sent, "delivery" | "woke" | "wakeSkipped">): string {
+export function wakeSkipNote({ delivery, woke, wakeSkipped, wakeLimit }: Pick<Sent, "delivery" | "woke" | "wakeSkipped" | "wakeLimit">): string {
   if (woke !== false || !wakeSkipped || delivery === "steer" || delivery === "turn") return ""
-  return ` — wake skipped: ${WAKE_SKIP_TEXT[wakeSkipped] ?? wakeSkipped}`
+  const detail = wakeLimit !== undefined && Number.isFinite(wakeLimit) && wakeLimit >= 1
+    ? wakeSkipped === "hop_cap" ? `hop limit reached (${wakeLimit} agent messages without a human turn)` : wakeSkipped === "budget" ? `wake budget spent (${wakeLimit} per 10 minutes)` : wakeSkipped === "item_budget" ? `item wake budget spent (${wakeLimit} wakes)` : undefined
+    : undefined
+  return ` — wake skipped: ${detail ?? WAKE_SKIP_TEXT[wakeSkipped] ?? wakeSkipped}`
 }

package/packages/spoke-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-spoke-sdk",
-  "version": "0.10.1",
+  "version": "0.11.1",
   "private": true,
   "description": "Harness-neutral spoke building blocks: hub connection, enrollment, tokens, idempotent deliver, prompt references, HarnessSpoke (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/src/central/agent/agent-limits.ts

@@ -0,0 +1,185 @@
+// Hub-wide safety limits: one versioned record, shared across users and pods. Console writes override hub.json.
+// (HC-1) hopCeiling: the highest hub-wide or team hop limit accepted (1–HOP_ABSOLUTE_MAX, default 100). A hub-wide
+// hopLimit above it is refused, never rewritten; raising it needs `confirm: true`; lowering needs none. A record
+// stored before the ceiling existed reads with the configured (hub.json or default) ceiling.
+import type { Bus, StateStore, Unsubscribe } from "../backend/types"
+import type { HubLaunches } from "../config"
+import { DEFAULT_LAUNCH_CAPS } from "./placement"
+import { AgentError } from "./errors"
+import { HOP_ABSOLUTE_MAX } from "./message-limits"
+import { HOP_CEILING_DEFAULT } from "../../protocol"
+
+const COLLECTION = "agent-limits"
+const OWNER = "hub"
+const KEY = "current"
+const POLL_MS = 30_000
+export const DEFAULT_ITEM_BUDGET = { wakes: 250, hours: 48 } as const
+export const DEFAULT_ITEM_LOOP = { messages: 12, windowMinutes: 30 } as const
+export interface ItemBudgetLimits { readonly wakes: number; readonly hours: number }
+export interface ItemLoopLimits { readonly messages: number; readonly windowMinutes: number }
+
+export interface AgentLimitsValue {
+  readonly hopLimit: number
+  /** (HC-1) Absent in records stored before the ceiling existed: the configured ceiling applies. */
+  readonly hopCeiling?: number
+  readonly launches: { readonly maxQueued: number; readonly maxActive: number; readonly perHour: number; readonly lostAfterMinutes?: number | false }
+  readonly itemBudget?: ItemBudgetLimits
+  readonly loop?: ItemLoopLimits
+  readonly sources?: { readonly hopLimit: AgentLimitsSource; readonly launches: AgentLimitsSource; readonly itemBudget?: AgentLimitsSource; readonly loop?: AgentLimitsSource; readonly hopCeiling?: AgentLimitsSource }
+}
+export type AgentLimitsSource = "default" | "hub.json" | "console"
+export interface AgentLimitsView extends AgentLimitsValue {
+  readonly hopCeiling: number
+  readonly revision: number
+  /** A stored record failed validation; revision still identifies it so an admin can replace it. */
+  readonly invalidStored?: boolean
+  readonly source: AgentLimitsSource
+  readonly sources: { readonly hopLimit: AgentLimitsSource; readonly launches: AgentLimitsSource; readonly itemBudget: AgentLimitsSource; readonly loop: AgentLimitsSource; readonly hopCeiling: AgentLimitsSource }
+}
+
+export class AgentLimits {
+  /** The ceiling (and its source) a record without one reads with. */
+  private readonly configuredCeiling: { readonly value: number; readonly source: AgentLimitsSource }
+  private current: AgentLimitsView
+  private off?: Unsubscribe
+  private poll?: ReturnType<typeof setInterval>
+  private stopped = false
+  private loaded = false
+  private retryTimer?: ReturnType<typeof setTimeout>
+  private resolveRetry?: () => void
+  private nextRetryAt?: number
+  constructor(private readonly state: StateStore, defaults: { readonly hopLimit: number; readonly hopCeiling?: number; readonly launchCaps?: HubLaunches }, sources: { readonly hopLimit?: boolean; readonly hopCeiling?: boolean; readonly launchCaps?: boolean } = {}, private readonly bus?: Bus, private readonly options: { readonly pollMs?: number; readonly retry?: (ms: number) => Promise<void>; readonly now?: () => number } = {}) {
+    this.configuredCeiling = { value: defaults.hopCeiling ?? HOP_CEILING_DEFAULT, source: sources.hopCeiling ? "hub.json" : "default" }
+    const provenance = { hopLimit: sources.hopLimit ? "hub.json" : "default", launches: sources.launchCaps ? "hub.json" : "default", itemBudget: "default", loop: "default", hopCeiling: this.configuredCeiling.source } as const
+    this.current = { hopLimit: defaults.hopLimit, hopCeiling: this.configuredCeiling.value, launches: { ...DEFAULT_LAUNCH_CAPS, ...defaults.launchCaps }, itemBudget: DEFAULT_ITEM_BUDGET, loop: DEFAULT_ITEM_LOOP, sources: provenance, source: provenance.hopLimit, revision: 0 }
+  }
+
+  snapshot(): AgentLimitsView { return this.current }
+  /** True only after the initial persisted limits were read; a stopped retry loop never counts as loaded. */
+  initialLoaded(): boolean { return this.loaded }
+  retryAfter(): number { return Math.max(1, Math.ceil(((this.nextRetryAt ?? (this.options.now ?? Date.now)() + 1_000) - (this.options.now ?? Date.now)()) / 1_000)) }
+
+  async start(): Promise<void> {
+    this.stopped = false
+    this.loaded = false
+    if (this.bus) {
+      try { this.off = await this.bus.subscribe("agent-limits", () => { void this.view().catch((cause) => console.error(`[hub] agent limits refresh failed: ${(cause as Error).message}`)) }) }
+      catch (cause) { console.error(`[hub] agent limits bus subscribe failed; initial read will retry: ${cause instanceof Error ? cause.message : String(cause)}`) }
+    }
+    let delay = 1_000
+    while (!this.stopped) {
+      try { await this.view(); if (!this.stopped) this.loaded = true; this.nextRetryAt = undefined; break }
+      catch (cause) {
+        console.error(`[hub] agent limits initial load failed; retrying in ${delay}ms: ${cause instanceof Error ? cause.message : String(cause)}`)
+        this.nextRetryAt = (this.options.now ?? Date.now)() + delay
+        await (this.options.retry ?? ((ms) => new Promise<void>((resolve) => {
+          this.resolveRetry = resolve
+          this.retryTimer = setTimeout(() => { this.retryTimer = undefined; this.resolveRetry = undefined; resolve() }, ms)
+        })))(delay)
+        delay = Math.min(delay * 2, 30_000)
+      }
+    }
+    if (this.stopped) return
+    this.poll = setInterval(() => { void this.view().catch((cause) => console.error(`[hub] agent limits refresh failed: ${(cause as Error).message}`)) }, this.options.pollMs ?? POLL_MS)
+  }
+
+  async stop(): Promise<void> {
+    this.stopped = true
+    this.nextRetryAt = undefined
+    if (this.retryTimer) clearTimeout(this.retryTimer)
+    this.retryTimer = undefined
+    this.resolveRetry?.()
+    this.resolveRetry = undefined
+    if (this.poll) clearInterval(this.poll)
+    this.poll = undefined
+    await this.off?.()
+    this.off = undefined
+  }
+
+  async view(): Promise<AgentLimitsView> {
+    const stored = await this.state.get<AgentLimitsValue>(OWNER, COLLECTION, KEY)
+    if (stored && stored.version >= this.current.revision) {
+      if (validValue(stored.value, this.configuredCeiling.value)) {
+        const ceiling = stored.value.hopCeiling !== undefined ? { value: stored.value.hopCeiling, source: stored.value.sources?.hopCeiling ?? "console" } : this.configuredCeiling
+        const sources = { hopLimit: stored.value.sources?.hopLimit ?? "console", launches: stored.value.sources?.launches ?? "console", itemBudget: stored.value.sources?.itemBudget ?? "default", loop: stored.value.sources?.loop ?? "default", hopCeiling: ceiling.source } as const
+        this.current = { ...stored.value, hopCeiling: ceiling.value, itemBudget: stored.value.itemBudget ?? DEFAULT_ITEM_BUDGET, loop: stored.value.loop ?? DEFAULT_ITEM_LOOP, sources, revision: stored.version, source: sources.hopLimit, invalidStored: false }
+      } else {
+        this.current = { ...this.current, revision: stored.version, invalidStored: true }
+      }
+    }
+    return this.current
+  }
+
+  async update(input: unknown): Promise<AgentLimitsView> {
+    if (!input || typeof input !== "object" || Array.isArray(input)) throw new AgentError("invalid", "Agent limits must be an object")
+    const x = input as Record<string, unknown>
+    if (!Number.isSafeInteger(x.revision) || (x.revision as number) < 0) throw new AgentError("invalid", "revision must be a nonnegative whole number")
+    if (x.hopCeiling !== undefined && (!Number.isSafeInteger(x.hopCeiling) || (x.hopCeiling as number) < 1 || (x.hopCeiling as number) > HOP_ABSOLUTE_MAX)) throw new AgentError("invalid", `hopCeiling must be 1–${HOP_ABSOLUTE_MAX}`)
+    if (x.confirm !== undefined && typeof x.confirm !== "boolean") throw new AgentError("invalid", "confirm is true or false")
+    if (!Number.isSafeInteger(x.hopLimit) || (x.hopLimit as number) < 1) throw new AgentError("invalid", "hopLimit must be a whole number of at least 1")
+    const l = x.launches
+    if (!l || typeof l !== "object" || Array.isArray(l)) throw new AgentError("invalid", "launches must be an object")
+    const launches = l as Record<string, unknown>
+    for (const key of ["maxQueued", "maxActive", "perHour"]) if (!Number.isSafeInteger(launches[key]) || (launches[key] as number) < 1 || (launches[key] as number) > 100_000) throw new AgentError("invalid", `launches.${key} must be 1–100000`)
+    const lost = launches.lostAfterMinutes
+    if (lost !== undefined && lost !== false && (!Number.isSafeInteger(lost) || (lost as number) < 0 || (lost as number) > 1440)) throw new AgentError("invalid", "launches.lostAfterMinutes must be 0–1440 or false")
+    const nextLaunches = { maxQueued: launches.maxQueued as number, maxActive: launches.maxActive as number, perHour: launches.perHour as number, ...(lost !== undefined ? { lostAfterMinutes: lost as number | false } : {}) }
+    // Compare against the persisted revision, not a possibly stale pod cache.
+    const before = await this.view()
+    const ceiling = (x.hopCeiling as number | undefined) ?? before.hopCeiling
+    if ((x.hopLimit as number) > ceiling) throw new AgentError("invalid", `hopLimit ${x.hopLimit} is above the hop ceiling ${ceiling}: lower the hop limit first, or raise the ceiling in the same save`)
+    // A script or a stale page cannot raise the ceiling silently.
+    if (ceiling > before.hopCeiling && x.confirm !== true) throw new AgentError("invalid", `Raising the hop ceiling from ${before.hopCeiling} to ${ceiling} needs confirm: true`)
+    const itemBudget = budgetOf(x.itemBudget === undefined ? before.itemBudget ?? DEFAULT_ITEM_BUDGET : x.itemBudget)
+    const loop = loopOf(x.loop === undefined ? before.loop ?? DEFAULT_ITEM_LOOP : x.loop)
+    const value: AgentLimitsValue = { hopLimit: x.hopLimit as number, hopCeiling: ceiling, launches: nextLaunches, itemBudget, loop, sources: {
+      hopLimit: x.hopLimit === before.hopLimit && !before.invalidStored ? before.sources.hopLimit : "console",
+      launches: JSON.stringify(nextLaunches) === JSON.stringify(before.launches) && !before.invalidStored ? before.sources.launches : "console",
+      itemBudget: x.itemBudget === undefined || JSON.stringify(itemBudget) === JSON.stringify(before.itemBudget) && !before.invalidStored ? before.sources.itemBudget : "console",
+      loop: x.loop === undefined || JSON.stringify(loop) === JSON.stringify(before.loop) && !before.invalidStored ? before.sources.loop : "console",
+      hopCeiling: ceiling === before.hopCeiling && !before.invalidStored ? before.sources.hopCeiling : "console",
+    } }
+    const result = await this.state.put(OWNER, COLLECTION, KEY, value, { ifVersion: x.revision as number })
+    if (!result.ok) throw new AgentError("conflict", "Agent limits changed; reload before saving", { extra: { currentRevision: result.version } })
+    this.current = { ...value, hopCeiling: ceiling, revision: result.version, source: value.sources!.hopLimit, sources: value.sources! as AgentLimitsView["sources"], invalidStored: false }
+    try { await this.bus?.publish("agent-limits", { revision: result.version }) }
+    catch (cause) { console.error(`[hub] agent limits notification failed; other pods will catch up on poll: ${(cause as Error).message}`) }
+    return this.current
+  }
+}
+
+/** `configuredCeiling`: the ceiling a record stored without one reads with (its hop limit must fit under it). */
+function validValue(value: unknown, configuredCeiling: number): value is AgentLimitsValue {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false
+  const v = value as Record<string, unknown>
+  const range = (n: unknown, min: number, max: number) => Number.isSafeInteger(n) && (n as number) >= min && (n as number) <= max
+  if (v.hopCeiling !== undefined && !range(v.hopCeiling, 1, HOP_ABSOLUTE_MAX)) return false
+  // A record stored without a ceiling must fit under the configured one (else it reads invalid; the admin replaces it).
+  const ceiling = (v.hopCeiling as number | undefined) ?? configuredCeiling
+  if (!range(v.hopLimit, 1, ceiling) || !v.launches || typeof v.launches !== "object" || Array.isArray(v.launches)) return false
+  const launches = v.launches as Record<string, unknown>
+  if (!["maxQueued", "maxActive", "perHour"].every((key) => range(launches[key], 1, 100_000))) return false
+  const lost = launches.lostAfterMinutes
+  if (lost !== undefined && lost !== false && !range(lost, 0, 1440)) return false
+  if (v.itemBudget !== undefined && !validBudget(v.itemBudget)) return false
+  if (v.loop !== undefined && !validLoop(v.loop)) return false
+  const sources = v.sources
+  return sources === undefined || (typeof sources === "object" && sources !== null && !Array.isArray(sources) && ["hopLimit", "launches"].every((key) => ["default", "hub.json", "console"].includes((sources as Record<string, string>)[key] ?? "")) && ["itemBudget", "loop"].every((key) => (sources as Record<string, string>)[key] === undefined || ["default", "console"].includes((sources as Record<string, string>)[key]!)) && ((sources as Record<string, string>).hopCeiling === undefined || ["default", "hub.json", "console"].includes((sources as Record<string, string>).hopCeiling!)))
+}
+
+const validBudget = (value: unknown): value is ItemBudgetLimits => isPair(value, "wakes", 10, 5_000, "hours", 1, 720)
+const validLoop = (value: unknown): value is ItemLoopLimits => isPair(value, "messages", 4, 200, "windowMinutes", 5, 240)
+function isPair(value: unknown, first: string, min: number, max: number, second: string, secondMin: number, secondMax: number): boolean {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false
+  const v = value as Record<string, unknown>
+  const inRange = (n: unknown, low: number, high: number) => Number.isSafeInteger(n) && (n as number) >= low && (n as number) <= high
+  return Object.keys(v).length === 2 && inRange(v[first], min, max) && inRange(v[second], secondMin, secondMax)
+}
+function budgetOf(value: unknown): ItemBudgetLimits {
+  if (!validBudget(value)) throw new AgentError("invalid", "itemBudget requires wakes 10–5000 and hours 1–720")
+  return value
+}
+function loopOf(value: unknown): ItemLoopLimits {
+  if (!validLoop(value)) throw new AgentError("invalid", "loop requires messages 4–200 and windowMinutes 5–240")
+  return value
+}

package/src/central/agent/app-decisions.ts

@@ -25,7 +25,7 @@ import type { ActingSwitch } from "./acting-switch"
 import type { AgentAudit, AuditDecision, AuditOutcome } from "./audit"
 import { AGENT_JSON_BODY_MAX, boundedText } from "./body"
 import { type AppSessionDeps, isAppSession, locateSession } from "./conversation"
-import { DECISION_STATES, type Decision, type DecisionState, type Decisions } from "./decisions"
+import { answerDetail, answerPicks, DECISION_STATES, type Decision, type DecisionState, type Decisions } from "./decisions"
 import { partyFromActor } from "./envelope"
 import { AgentError } from "./errors"
 import type { Message } from "./messages"
@@ -73,16 +73,17 @@ function ownership(deps: AppSessionDeps, actor: AppActor, userID: string) {
   }
 }
 
-async function answerBody(request: Request): Promise<{ option?: string; text?: string }> {
+async function answerBody(request: Request): Promise<{ option?: string; text?: string; picks?: Record<string, string> }> {
   const raw = await boundedText(request, AGENT_JSON_BODY_MAX)
   const body: unknown = JSON.parse(raw)
   if (typeof body !== "object" || body === null || Array.isArray(body)) throw new AgentError("invalid", "Body must be a JSON object")
   const input = body as Record<string, unknown>
-  if ("via" in input) throw new AgentError("invalid", "An app's answer has no via", { hint: "Send {option} or {text}" })
+  if ("via" in input) throw new AgentError("invalid", "An app's answer has no via", { hint: "Send {option}, {picks} or {text}" })
   for (const key of ["option", "text"] as const) {
     if (input[key] !== undefined && typeof input[key] !== "string") throw new AgentError("invalid", `${key} must be a string`)
   }
-  return { ...(typeof input.option === "string" ? { option: input.option } : {}), ...(typeof input.text === "string" ? { text: input.text } : {}) }
+  const picks = answerPicks(input.picks)
+  return { ...(typeof input.option === "string" ? { option: input.option } : {}), ...(typeof input.text === "string" ? { text: input.text } : {}), ...(picks ? { picks } : {}) }
 }
 
 function stateQuery(raw: string | null): DecisionState | undefined {
@@ -129,7 +130,7 @@ export function appDecisionRoutes(deps: AppDecisionDeps): { readonly answerable:
             })
             if (answered.reply) deps.publish?.(user.id, answered.reply)
             await record("allow", "ok", `Decision ${params.id!}`)
-            await deps.store.audit({ actor: user.id, action: "decision.answer", target: params.id!, detail: `app:${actor.tokenID} ${answered.decision.answer?.option ?? "text"}` })
+            await deps.store.audit({ actor: user.id, action: "decision.answer", target: params.id!, detail: `app:${actor.tokenID} ${answerDetail(answered.decision.answer)}` })
             return Response.json({ decision: answered.decision }, { headers: NO_STORE })
           } catch (cause) {
             // Only attempts on the app's own sessions' Decisions (unknown or foreign IDs are not audited).