@huynle/hub 0.8.0 → 0.8.1

package/src/central/agent/delivery.ts

@@ -7,13 +7,16 @@
 //   {feature: "deliver"} and nothing is stored. No fallback through steer/turn.
 // - Modes: plain msg → delivery "queue" (after the running turn), ask/reply/decline/urgent → "steer" (also the
 //   first msg after a primer to an idle session: the two then share one model call, quirk hzmcqwpj); wake
-//   unless wake:false, a subagent recipient, the hop cap (alerted once when crossed) or a spent wake budget.
+//   unless wake:false, a subagent recipient, the hop cap (alerted once when crossed) or a spent wake budget; Sent
+//   says whether it woke (woke) and, when not, why (wakeSkipped: wake_false | subagent | hop_cap | budget).
 // - Roles: one holder, the idle one (by real evidence) else the most recently active, else (all offline) the
 //   one seen last; the message records the holder generation. sendAll: every holder, a message each. A session
 //   never messages itself: it is left out of a role it holds, and an address naming only it is invalid.
 // - Pending: no deliver-capable connection reports the recipient (offline) or every one failed (including an
 //   OpenCode spoke refusing a routine wake:false msg while the recipient's turn runs, RF-05) → kept for
-//   PENDING_MS in the StateStore and delivered oldest first on the user's next sessions frame (onSessions). In a
+//   PENDING_MS in the StateStore and delivered oldest first on the user's next sessions frame (onSessions). One
+//   still pending after PENDING_MS expires (the loop's tick, or a flush that finds it): delivery "expired", and its
+//   sender is told (a session by a quiet hub notice, the user by an alert, everyone through the journal). In a
 //   cluster (deps.locks) each (user, session) flush holds a lease (deliver:<user>:<session>) and re-reads the
 //   entry under it, so a spoke reconnecting to another pod meanwhile never gets a message twice. A flush stops at a
 //   session's first failed delivery (its later messages wait, in order, for the next frame: one round trip per busy
@@ -37,8 +40,12 @@
 //   for the user (their stored-only inbox; nothing goes to a spoke); a msg alerts the user ("user"), an ask is a
 //   Decision's carrier (./decisions pushes it). The user cannot message @me; `@me.project` is malformed.
 // - Loop protection (./message-limits): pair/user rate limits before storing, hop per message, human turns
-//   (console, voice, typed in the harness) reset a session's chain (humanTurn).
+//   (console, voice, typed in the harness) reset a session's chain (humanTurn). Apps keep no depth (S1): a new
+//   msg/ask from an app is hop 1 plus its relay depth (what OTHER sessions sent it in the last 5 minutes, so a
+//   relay loop through an app still reaches the hop cap), an app's reply or decline counts up from the message it
+//   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 { isDeliverResult } from "../../protocol"
 import { randomBytes } from "node:crypto"
 import type { Clock, Counters, Locks, StateStore, Timers } from "../backend/types"
@@ -80,8 +87,8 @@ export type DeliverSend = (connID: string, req: DeliverRequest) => Promise<Deliv
  * ask stayed unanswered by an idle recipient after every re-wake.
  */
 export interface DeliveryAlert {
-  /** user: a session or app sent the user (@me) a message. */
-  readonly kind: "hopCap" | "unanswered" | "user"
+  /** user: a session or app sent the user (@me) a message; expired: the user's message stayed pending for 24 h. */
+  readonly kind: "hopCap" | "unanswered" | "user" | "expired"
   /** The recipient session (user: the sending session, "" for an app). */
   readonly sessionID: string
   readonly messageID: string
@@ -113,8 +120,12 @@ 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
+  /** 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>
+  /** 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). */
   readonly users?: () => Iterable<string> | Promise<Iterable<string>>
   /** Cluster mode: a pending flush holds a lease per (user, session), so two pods never deliver the same message. */
@@ -136,6 +147,11 @@ export interface SendOptions {
   readonly urgent?: boolean
   /** Asks only. */
   readonly expiresInMs?: number
+  /**
+   * Hub-internal, never from a request body: the message continues a chain at least this deep (its hop is the
+   * larger of its own and this). Team intake passes the submitting session's depth + 1.
+   */
+  readonly chainHop?: number
 }
 
 export interface Sent {
@@ -144,6 +160,8 @@ export interface Sent {
   readonly delivery?: DeliveryState
   /** Whether it was sent to wake its recipient (false: wake:false, a subagent, the hop cap or a spent wake budget). */
   readonly woke?: boolean
+  /** Why it was not (only when woke is false). */
+  readonly wakeSkipped?: WakeSkip
 }
 
 /** A reply or decline as sent, with the message it answered. */
@@ -247,7 +265,7 @@ export class Delivery {
     this.newID = deps.newID ?? newMessageID
     this.owner = deps.owner ?? `delivery-${process.pid}-${randomBytes(4).toString("hex")}`
     this.messages = new Messages({ state: deps.state, now, newID: this.newID })
-    this.hops = new HopTracker({ state: deps.state, now })
+    this.hops = new HopTracker({ state: deps.state, now, ...(deps.relayWindowMs === undefined ? {} : { relayWindowMs: deps.relayWindowMs }) })
     this.limiter = new MessageLimiter({ counters: deps.counters, now, ...(deps.limits ? { limits: deps.limits } : {}) })
     // An explicit (re)name primes again, so the session learns its new address.
     deps.directory.onNamed?.((userID, sessionID) => void this.prime(userID, sessionID, { again: true }))
@@ -367,6 +385,11 @@ export class Delivery {
       return
     }
     for (const userID of users) {
+      try {
+        await this.expirePending(userID)
+      } catch (cause) {
+        console.error(`[hub] pending expiry failed: ${cause instanceof Error ? cause.message : String(cause)}`)
+      }
       try {
         await this.rewake(userID)
       } catch (cause) {
@@ -404,7 +427,7 @@ export class Delivery {
     const from = this.party(userID, actor)
     const recipient: Party = { kind: "user" }
     await this.limiter.admit(userID, from, recipient)
-    const hop = await this.hops.next(userID, from)
+    const hop = await this.hops.next(userID, from, { to: recipient })
     const message = await this.messages.send(userID, {
       from,
       to: USER_ADDRESS,
@@ -428,7 +451,7 @@ export class Delivery {
     await this.deps.inbound?.admit(userID, from, sessionID, kind)
     this.gate(userID, sessionID)
     await this.limiter.admit(userID, from, recipient)
-    const hop = await this.hops.next(userID, from)
+    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
     const message = await this.messages.send(userID, {
       from,
@@ -440,15 +463,15 @@ export class Delivery {
       ...(generation === undefined ? {} : { generation }),
       ...(options.expiresInMs === undefined ? {} : { expiresInMs: options.expiresInMs }),
     })
-    await this.hops.received(userID, recipient, hop)
+    await this.hops.received(userID, recipient, hop, from)
     this.users.add(userID)
-    const wanted = options.wake !== false && entry.parentID === undefined
-    const wake = await this.wakeFor(userID, message, wanted)
-    if (kind === "ask" && wanted && !overHopCap(hop)) {
+    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 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, wake, options.urgent === true)
+    return this.deliver(userID, message, sessionID, skipped, options.urgent === true)
   }
 
   private schedule(): void {
@@ -555,33 +578,38 @@ export class Delivery {
     }
     if (to && original) await this.deps.teams?.answer(userID, from, original, to, kind, this.limiter)
     if (to) await this.limiter.admit(userID, from, to)
-    const hop = await this.hops.next(userID, from)
+    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 }) })
     const { message } = answered
-    await this.hops.received(userID, message.recipient, hop)
+    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 wake = await this.wakeFor(userID, message, options.wake !== false && !this.isSubagent(userID, sessionID))
-    return { ...(await this.deliver(userID, message, sessionID, wake, true)), original: answered.original }
+    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 }
   }
 
-  /** Whether the message may start a turn: wanted, under the hop cap (alerting once at the cap), wake budget left. */
-  private async wakeFor(userID: string, message: Message, wanted: boolean): Promise<boolean> {
-    if (!wanted || message.recipient.kind !== "session") return false
+  /**
+   * 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) {
         this.deps.alert?.(userID, {
           kind: "hopCap",
           sessionID: message.recipient.sessionID,
           messageID: message.id,
-          text: `Sessions messaged each other ${HOP_CAP} times without you; further messages no longer wake them`,
+          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`,
         })
       }
-      return false
+      return "hop_cap"
     }
-    return this.limiter.wake(userID, message.recipient)
+    return (await this.limiter.wake(userID, message.recipient)) ? undefined : "budget"
   }
 
   /** The replier's generation of the role the original reached (undefined: not a role, or not held now). */
@@ -619,16 +647,18 @@ 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, wake: boolean, urgent: boolean): Promise<Sent> {
+  private async deliver(userID: string, message: Message, sessionID: string, skipped: WakeSkip | undefined, urgent: boolean): Promise<Sent> {
+    const wake = skipped === undefined
+    const woke = wake ? { woke: true } : { woke: false, wakeSkipped: skipped }
     // 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)
     const delivered = await this.attempt(userID, message, sessionID, wake, urgent)
-    if (delivered) return { ...delivered, woke: wake }
+    if (delivered) return { ...delivered, ...woke }
     const at = this.now()
     const pending: Pending = { messageID: message.id, sessionID, wake, urgent, at, expiresAt: at + PENDING_MS }
     await this.deps.state.put(userID, PENDING, message.id, pending)
-    return { message: (await this.messages.setDelivery(userID, message.id, "pending")) ?? message, delivery: "pending", woke: wake }
+    return { message: (await this.messages.setDelivery(userID, message.id, "pending")) ?? message, delivery: "pending", ...woke }
   }
 
   /** Tries each deliver-capable connection in turn (same message id: the harness dedupes it). */
@@ -671,7 +701,11 @@ export class Delivery {
           this.flushStats.skipped++
           continue
         }
-        const message = value.expiresAt > this.now() ? await this.messages.get(userID, value.messageID) : undefined
+        if (value.expiresAt <= this.now()) {
+          await this.expireEntry(userID, key, value, version)
+          continue
+        }
+        const message = await this.messages.get(userID, value.messageID)
         // Gone, or an ask that closed (expired) while it waited: nothing to deliver.
         if (!message || (message.kind === "ask" && message.state !== "open")) {
           await this.deps.state.delete(userID, PENDING, key, { ifVersion: version })
@@ -695,6 +729,46 @@ export class Delivery {
     }
   }
 
+  /** The loop's sweep: the user's messages pending past PENDING_MS expire (their senders are told). */
+  private async expirePending(userID: string): Promise<void> {
+    const t = this.now()
+    for (const { key, value, version } of await this.deps.state.list<Pending>(userID, PENDING)) {
+      if (value.expiresAt <= t) await this.expireEntry(userID, key, value, version)
+    }
+  }
+
+  /**
+   * A pending message that waited PENDING_MS: removed (once: version-checked), marked "expired", and its sender
+   * told: a session by a quiet notice (wake:false, never the message text), the user by an alert; the change is
+   * journaled (deps.expired) for every sender, an app included. An ask that already closed is dropped silently.
+   */
+  private async expireEntry(userID: string, key: string, value: Pending, version: number): Promise<void> {
+    if (!(await this.deps.state.delete(userID, PENDING, key, { ifVersion: version })).ok) return
+    const current = await this.messages.get(userID, value.messageID)
+    if (!current || (current.kind === "ask" && current.state !== "open" && current.state !== "expired")) return
+    const message = (await this.messages.setDelivery(userID, current.id, "expired")) ?? current
+    const what = `${message.kind} ${message.id} to ${message.to}`
+    try {
+      this.deps.expired?.(userID, message)
+    } catch (cause) {
+      console.error(`[hub] pending expiry journal failed: ${cause instanceof Error ? cause.message : String(cause)}`)
+    }
+    const { from } = message
+    if (from.kind === "user") {
+      this.deps.alert?.(userID, { kind: "expired", sessionID: value.sessionID, messageID: message.id, text: `Your ${message.kind} to ${message.to} was not delivered: its session stayed offline or busy for 24 h` })
+    } else if (from.kind === "session") {
+      const id = this.newID()
+      await this.request(userID, from.sessionID, {
+        op: "deliver",
+        sessionID: from.sessionID,
+        messageID: id,
+        text: `[hub] notice · ${what} was not delivered: its session stayed offline or busy for 24 h · ${id}`,
+        wake: false,
+        meta: { kind: "msg", from: "hub", to: wireAddress(from), delivery: "queue" },
+      })
+    }
+  }
+
   /** Takes the (user, session) flush lease once per flush (always true without locks); false: another process flushes it. */
   private async lease(userID: string, sessionID: string, leases: Map<string, boolean>): Promise<boolean> {
     const { locks } = this.deps

package/src/central/agent/errors.ts

@@ -35,6 +35,8 @@ export const AGENT_ERROR_STATUS = {
   internal: 500,
   /** The machine is offline (actions only; messages queue instead). */
   offline: 503,
+  /** (FX-07) The hub's state did not answer in time (`retryAfter`, seconds): refused, try again. */
+  busy: 503,
 } as const satisfies Record<string, number>
 
 export type AgentErrorCode = keyof typeof AGENT_ERROR_STATUS

package/src/central/agent/escalation.ts

@@ -25,7 +25,7 @@ import type { BlockerRecommendation } from "../../status"
 import type { Escalation } from "./acting"
 import type { AgentActor, UserActor } from "./actor"
 import type { AgentAudit } from "./audit"
-import { type ActOutcome, type Decision, type DecisionActor, type Decisions, WHY_MAX } from "./decisions"
+import { type ActOutcome, type Decision, type DecisionActor, type Decisions, decisionRequest, WHY_MAX } from "./decisions"
 import { type Party, partyFromActor, partyKey, partyLabel } from "./envelope"
 import { AgentError } from "./errors"
 import type { Message } from "./messages"
@@ -168,7 +168,15 @@ export class Escalations {
         about: [escalation.sessionID],
       },
       {
-        action: { kind: "permission", requestID: escalation.requestID, rootID: escalation.rootID, sessionID: escalation.sessionID, always: escalation.always },
+        action: {
+          kind: "permission",
+          requestID: escalation.requestID,
+          rootID: escalation.rootID,
+          sessionID: escalation.sessionID,
+          always: escalation.always,
+          ...(escalation.request ? { request: decisionRequest(escalation.request) } : {}),
+          ...(escalation.evaluation.reason ? { reason: escalation.evaluation.reason.slice(0, WHY_MAX) } : {}),
+        },
         quiet: pushes > 1,
       },
     )

package/src/central/agent/events.ts

@@ -193,7 +193,13 @@ export function launchEvent(launch: Launch): EventInput {
     type: "launch.changed",
     family: "launch",
     subject: { launchID: launch.id, ...(launch.sessionID !== undefined ? { sessionID: launch.sessionID } : {}) },
-    data: { state: launch.state, ...(launch.outcome !== undefined ? { outcome: launch.outcome } : {}), ...(launch.name !== undefined ? { name: launch.name } : {}) },
+    data: {
+      state: launch.state,
+      ...(launch.outcome !== undefined ? { outcome: launch.outcome } : {}),
+      ...(launch.name !== undefined ? { name: launch.name } : {}),
+      // FX-02: a queued launch's wait kind (never its text); the engine journals a change of kind only.
+      ...(launch.state === "queued" && launch.waiting ? { wait: launch.waiting.wait } : {}),
+    },
     ...(launch.by !== undefined ? { audience: { by: launch.by } } : {}),
   }
 }