@huynle/hub 0.10.0 → 0.11.0

package/src/central/agent/delivery.ts

@@ -58,7 +58,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_CAP, HOP_CAP_CEILING, HopTracker, MessageLimiter, type MessageLimits } from "./message-limits"
 import { parseAddress } from "./names"
 import { type Delivery as DeliveryState, type Message, Messages, newMessageID } from "./messages"
 
@@ -126,10 +126,16 @@ 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>
+  /** 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, absolute ceiling 100). */
+  readonly hopLimit?: 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,7 +147,7 @@ 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
 }
@@ -273,6 +279,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_CAP_CEILING)) throw new Error(`hopLimit must be 1–${HOP_CAP_CEILING}`)
     this.deps = deps
     const now = (this.now = deps.now ?? Date.now)
     this.timers = deps.timers ?? defaultTimers
@@ -348,6 +355,17 @@ export class Delivery {
     return this.hops.humanTurn(userID, sessionID)
   }
 
+  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> {
@@ -489,8 +507,12 @@ 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)
+    const limit = Math.min(context?.limit ?? this.deps.hopLimit ?? HOP_CAP, this.deps.hopLimit ?? HOP_CAP)
+    const skipped = await this.wakeFor(userID, message, unwanted, limit, context?.teamID)
+    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)
     }
@@ -612,7 +634,8 @@ export class Delivery {
     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)
+    const context = await this.deps.teams?.hopContext(userID, from, message.recipient)
+    const skipped = await this.wakeFor(userID, message, unwanted, Math.min(context?.limit ?? this.deps.hopLimit ?? HOP_CAP, this.deps.hopLimit ?? HOP_CAP), context?.teamID)
     return { ...(await this.deliver(userID, message, sessionID, skipped, true)), original: answered.original }
   }
 
@@ -620,16 +643,23 @@ export class Delivery {
    * 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> {
+  private async wakeFor(userID: string, message: Message, unwanted: WakeSkip | undefined, limit = this.deps.hopLimit ?? HOP_CAP, teamID?: string): 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) {
+    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"

package/src/central/agent/grant-routes.ts

@@ -1,6 +1,7 @@
 // /api/agent/grants (design §5, §7): the user's grants. User actors only (allow {}): the device cookie (same-origin
 // writes, checked by the agent framework) or a device token. A session or app token never creates, edits, reads
-// or revokes a grant (escalation guard). Answers {grant} / {grants}, never cached; the owner is not echoed.
+// or revokes a grant on the admin routes (escalation guard). /mine is holder-scoped; a user has no holder.
+// Answers {grant} / {grants}, never cached; the owner is not echoed.
 //
 //   POST   /api/agent/grants       create (201)          GET /api/agent/grants      list, newest first
 //   GET    /api/agent/grants/:id   one grant             PUT /api/agent/grants/:id  replace (holder fixed)
@@ -37,6 +38,18 @@ export function grantRoutes(grants: Grants, now: () => number = Date.now, reques
           } satisfies AgentRoute,
         ]
       : []),
+    {
+      method: "GET", path: `${PREFIX}/mine`, allow: { session: true, scope: "messages:read" },
+      handle: async ({ actor }) => Response.json({ grants: (await grants.held(actor)).map((g) => grantView(g, now())) }, { headers: NO_STORE }),
+    },
+    {
+      method: "GET", path: `${PREFIX}/mine/:id`, allow: { session: true, scope: "messages:read" },
+      handle: async ({ actor, params }) => one(await grants.heldGrant(actor, params.id!)),
+    },
+    {
+      method: "DELETE", path: `${PREFIX}/mine/:id`, allow: { session: true, scope: "messages:send" },
+      handle: async ({ actor, params }) => one(await grants.revokeHeld(actor, params.id!)),
+    },
     {
       method: "POST",
       path: PREFIX,

package/src/central/agent/grants.ts

@@ -136,6 +136,29 @@ export class Grants {
     return (await this.all(owner)).sort((a, b) => b.created - a.created || (a.id < b.id ? -1 : 1)).map((g) => ({ ...g, state: grantState(g, at) }))
   }
 
+  /** Grants currently held by this credential; a user credential has no session/app holder. */
+  async held(actor: AgentActor): Promise<GrantView[]> {
+    if (actor.kind === "user") return []
+    return (await this.list(actor.userID)).filter((grant) => grant.owner === actor.userID && this.holds(grant, actor))
+  }
+
+  /** A holder cannot inspect another holder's grant (including an unheld role). */
+  async heldGrant(actor: AgentActor, id: string): Promise<Grant> {
+    if (actor.kind === "user") throw notFound()
+    const grant = await this.get(actor.userID, id)
+    if (grant.owner !== actor.userID || !this.holds(grant, actor)) throw notFound()
+    return grant
+  }
+
+  /** Re-check holder inside the versioned mutation, so a role lost after a read cannot revoke it. */
+  async revokeHeld(actor: AgentActor, id: string): Promise<Grant> {
+    await this.heldGrant(actor, id)
+    return this.change(actor.userID, id, "grant.revoke", (grant, at) => {
+      if (actor.kind === "user" || grant.owner !== actor.userID || !this.holds(grant, actor)) throw notFound()
+      return { ...grant, revokedAt: at }
+    })
+  }
+
   /**
    * Replaces an active grant with a new spec (its expiry restarts now); id, holder (and its pin) and created
    * stay. Changing the holder is invalid (revoke and create instead); an ended grant is gone.

package/src/central/agent/launch-engine.ts

@@ -746,7 +746,7 @@ export class LaunchEngine {
         const workspace = work?.workspace ?? (launch ? leftWorkspace(launch, report) : undefined)
         if (!workspace) continue
         if (HARNESS_UP.has(report.phase)) await nodeOps.requestNode(node.connID, { op: "stop", launchID: report.launchID, workspace, mode: "kill" })
-        await nodeOps.requestNode(node.connID, { op: "cleanup", launchID: report.launchID, workspace, policy: work?.cleanup ?? (workspace.reused ? "keep" : "remove") })
+        await nodeOps.requestNode(node.connID, { op: "cleanup", launchID: report.launchID, workspace, policy: work?.cleanup ?? (launch?.spec.end.cleanup ?? (workspace.reused ? "keep" : "remove")) })
         this.cleanupTries.delete(report.launchID)
         this.cleanupLogged.delete(report.launchID)
       } catch (cause) {
@@ -1122,6 +1122,8 @@ export class LaunchEngine {
       // A lost launch whose session a spoke still reports keeps its workspace (never removed under a live session).
       const sessionLive = outcome === "lost" && work.sessionID !== undefined && this.deps.registry.hasSession(work.sessionID)
       const policy: CleanupPolicy = outcome === "needs_user" || sessionLive ? "keep" : !work.prompted ? "remove" : launch.spec.end.cleanup
+      // Reconciliation must replay the policy actually applied, not the launch's original preference.
+      await this.updateWork(userID, id, { cleanup: policy })
       const node = launch.machineID !== undefined ? this.deps.nodes.forMachine(launch.machineID) : undefined
       if (node) {
         if (work.started) {
@@ -1145,11 +1147,9 @@ export class LaunchEngine {
         } catch (cause) {
           // The node may still hold the launch (and its slot): reconcile retries with this policy.
           notes.push(`workspace cleanup failed: ${errorText(cause)}; retried later`)
-          await this.updateWork(userID, id, { cleanup: policy })
         }
       } else {
         notes.push("workspace cleanup waits for the node")
-        await this.updateWork(userID, id, { cleanup: policy })
       }
     }
     try {

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

@@ -28,9 +28,12 @@ import type { Clock, Counters, StateStore } from "../backend/types"
 import { type Party, partyKey } from "./envelope"
 import { AgentError } from "./errors"
 import { updateVersioned } from "./versioned"
+import { TEAM_LIMITS } from "../../protocol"
 
 /** Hops a reply chain may take without a human turn. */
 export const HOP_CAP = 8
+/** Absolute ceiling on user-configured hop limits, independent of hub.json. */
+export const HOP_CAP_CEILING = TEAM_LIMITS.hopLimit
 /** A depth no message refreshed for this long is forgotten. */
 export const HOP_TTL_MS = 24 * 60 * 60_000
 

package/src/central/agent/routes.ts

@@ -67,6 +67,7 @@ import { isConciergeLaunch } from "../concierge/supervisor"
 import type { ConciergeService } from "../concierge/service"
 import type { SessionIntent } from "../../protocol"
 import type { SessionIntents } from "./intents"
+import type { NodeRegistry } from "../nodes"
 import { intentRoutes } from "./intent-routes"
 import { contextCardRoutes } from "../context-cards/routes"
 import type { ContextCardService } from "../context-cards/service"
@@ -98,6 +99,8 @@ export interface AgentRoute {
 /** What the agent API needs from the hub. */
 export interface AgentDeps {
   readonly store: Store
+  /** Owner's connected launch nodes: read-only user route; never expose connection IDs or launch internals. */
+  readonly nodes?: Pick<NodeRegistry, "list">
   /** (AF1) Connect an app: the connected-app token verifier and the app-clients/connections routes when given. */
   readonly connect?: AppConnect
   /** (AF2) Speech for apps: POST /api/agent/speech/{transcribe,speak} (scope speech:use) when given. */
@@ -238,6 +241,14 @@ export function agentRoutes(deps: AgentDeps): AgentRoute[] {
   const feed = deps.feed ?? new MessageFeed()
   const appDecisions = appDecisionParts(deps, feed)
   const routes: AgentRoute[] = [
+    ...(deps.nodes ? [{
+      method: "GET", path: `${AGENT_PREFIX}/launch-nodes`, allow: {},
+      handle: ({ user }) => Response.json({ nodes: deps.nodes!.list(user.id).map((node) => ({
+        machineID: node.machineID, machineName: node.machineName, workspaceRoots: node.workspaceRoots,
+        capacity: node.capacity, used: node.used, free: node.free, runtimes: node.runtimes,
+        labels: node.labels, draining: node.draining,
+      })) }, { headers: { "cache-control": "no-store" } }),
+    } satisfies AgentRoute] : []),
     ...(deps.directory ? directoryRoutes({ directory: deps.directory, store: deps.store, ...(deps.agentEvents ? { events: deps.agentEvents } : {}), ...(deps.registry ? { registry: deps.registry } : {}), ...(deps.grants ? { grants: deps.grants } : {}), ...(deps.acting ? { acting: deps.acting } : {}), ...(deps.audit ? { audit: deps.audit } : {}), ...(deps.eventCursorKeys ? { previewKeys: deps.eventCursorKeys } : {}), ...(deps.teamDiscovery ? { discovery: deps.teamDiscovery } : {}), ...intentReads(deps), ...conciergeReads(deps) }) : []),
     ...(deps.directory && deps.intents ? intentRoutes({ intents: deps.intents, directory: deps.directory, store: deps.store, ...(deps.registry ? { registry: deps.registry } : {}), ...(deps.teamDiscovery ? { discovery: deps.teamDiscovery } : {}) }) : []),
     ...(deps.directory && deps.contextCards ? contextCardRoutes({ cards: deps.contextCards, directory: deps.directory, ...(deps.teamDiscovery ? { discovery: deps.teamDiscovery } : {}) }) : []),

package/src/central/agent/subscriptions.ts

@@ -245,6 +245,8 @@ export interface SubscriptionsDeps {
   readonly send: SubscriptionSend
   /** The session's message hop depth (HopTracker.depth). */
   readonly hopDepth: (userID: string, sessionID: string) => Promise<number>
+  /** Hub-wide hop ceiling (team notices are not session-to-session messages). */
+  readonly hopLimit?: number
   /** Directory facts of these sessions (deleted and unknown ones absent). */
   readonly entries: (userID: string, sessionIDs: readonly string[]) => ReadonlyMap<string, SubscriptionEntry>
   /** The sessions an address names for the subscriber (its visibility); throws not_found / invalid / ambiguous. */
@@ -858,7 +860,7 @@ export class Subscriptions {
       if (scoped && !scoped(subject)) continue
       const cause = isMessage && subject.senderID !== undefined && subject.senderID.startsWith("ses_") ? subject.senderID : (subject.sessionID ?? target)
       const depth = await this.depth(ctx, cause)
-      if (depth + 1 > HOP_CAP) {
+      if (depth + 1 > (this.deps.hopLimit ?? HOP_CAP)) {
         suppressed++
         continue
       }

package/src/central/config.ts

@@ -15,6 +15,7 @@ import { readContextCards, type ContextCardsConfig } from "./context-cards/confi
 import { checkReleaseBase } from "./install/render"
 import { cspMode, type CspMode } from "./csp"
 import { parseDenyCidrs } from "./fetcher"
+import { HOP_CAP, HOP_CAP_CEILING } from "./agent/message-limits"
 
 export const GOOGLE_ISSUER = "https://accounts.google.com"
 
@@ -70,6 +71,8 @@ export interface CentralConfig {
   readonly auth: AuthConfig
   /** hub.json `agents.never`: permission patterns no agent may ever approve, for every user (design §5, §7). */
   readonly agentsNever: readonly string[]
+  /** hub.json `agents.hopLimit`: global maximum agent-only hops before a wake is skipped. */
+  readonly hopLimit: number
   /** hub.json `agents.launches`: per-user launch caps, only those set (placement fills in its defaults). */
   readonly launchCaps?: HubLaunches
   /** hub.json `agents.webhooks.allowPrivate`: webhooks may target http, loopback, private and local hosts (admin opt-in). */
@@ -138,6 +141,7 @@ export interface HubLaunches {
 export interface HubAgents {
   /** Normalised `action[:glob]` patterns (see agent/policy.ts), duplicates dropped. */
   readonly never?: readonly string[]
+  readonly hopLimit?: number
   readonly launches?: HubLaunches
   readonly webhooks?: HubWebhooks
   /** (AF2) Per-credential app speech quotas: any subset of SPEECH_RATE_LIMITS. */
@@ -169,7 +173,7 @@ type Env = Readonly<Record<string, string | undefined>>
 
 const HUB_KEYS = new Set(["host", "port", "publicURL", "stateDir", "speech", "auth", "agents", "cluster", "contextCards"])
 const CLUSTER_KEYS = ["database", "valkey"] as const
-const AGENTS_KEYS = new Set(["never", "launches", "webhooks", "speechQuotas"])
+const AGENTS_KEYS = new Set(["never", "launches", "webhooks", "speechQuotas", "hopLimit"])
 /** The largest speech quota hub.json may set (counts and characters). */
 const SPEECH_QUOTA_MAX = 1_000_000_000
 const WEBHOOK_KEYS = new Set(["allowPrivate", "allowPrivateHosts"])
@@ -350,11 +354,13 @@ function readHubAgents(raw: unknown, file: string, warnings: string[], fail: (me
   if (!isObj(raw)) fail("agents must be an object")
   const input = raw as Record<string, unknown>
   for (const key of Object.keys(input)) if (!AGENTS_KEYS.has(key)) warnings.push(`${file}: unknown key "agents.${key}" ignored`)
+  if (input.hopLimit !== undefined && (!Number.isSafeInteger(input.hopLimit) || (input.hopLimit as number) < 1 || (input.hopLimit as number) > HOP_CAP_CEILING))
+    fail(`agents.hopLimit must be a whole number from 1 to ${HOP_CAP_CEILING}`)
   const launches = input.launches === undefined ? undefined : readHubLaunches(input.launches, file, warnings, fail)
   const never = input.never === undefined ? undefined : readNever(input.never, fail)
   const webhooks = input.webhooks === undefined ? undefined : readHubWebhooks(input.webhooks, file, warnings, fail)
   const speechQuotas = input.speechQuotas === undefined ? undefined : readSpeechQuotas(input.speechQuotas, file, warnings, fail)
-  return { ...(never ? { never } : {}), ...(launches ? { launches } : {}), ...(webhooks ? { webhooks } : {}), ...(speechQuotas ? { speechQuotas } : {}) }
+  return { ...(never ? { never } : {}), ...(input.hopLimit !== undefined ? { hopLimit: input.hopLimit as number } : {}), ...(launches ? { launches } : {}), ...(webhooks ? { webhooks } : {}), ...(speechQuotas ? { speechQuotas } : {}) }
 }
 
 /** (AF2) `agents.speechQuotas`: {transcribe?: {perMinute?, perHour?}, speak?: {perMinute?, perHour?, charsPerHour?}}. */
@@ -601,6 +607,7 @@ export function centralConfig(rawEnv: Env = process.env, home: string = homedir(
     ...(file.speech ? { speech: file.speech } : {}),
     auth,
     agentsNever: [...(file.agents?.never ?? [])],
+    hopLimit: file.agents?.hopLimit ?? HOP_CAP,
     ...(file.agents?.launches ? { launchCaps: { ...file.agents.launches } } : {}),
     ...(file.agents?.webhooks?.allowPrivate === true ? { webhooksAllowPrivate: true as const } : {}),
     ...(file.agents?.webhooks?.allowPrivateHosts?.length ? { webhooksPrivateHosts: [...file.agents.webhooks.allowPrivateHosts] } : {}),