@huynle/hub 0.6.0 → 0.7.1

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

@@ -0,0 +1,264 @@
+// Launches per user (design §6.1, §9; decision znbg8xa5), stored in the StateStore collection "launches" under
+// their id. The launch engine (P4-T8) drives them; this module owns the records, the state machine and idempotency.
+// - States: queued → placing → provisioning → running → ended{outcome}. placing may fall back to queued (no node
+//   could take it yet); every live state may end; ended is final. Each step records its reason and time (history,
+//   bounded: the first step and the latest ones). An illegal step throws LaunchTransitionError (code gone when the
+//   launch already ended, else invalid) and changes nothing; writes are version-checked, so of two racing steps
+//   only one applies.
+// - provisioning needs the machine, running the session; ended needs an outcome (idle, needs_user, failed,
+//   timeout, stopped, lost), and only ended may carry one.
+// - Idempotency: a spec with a key claims it in the StateStore (namespace `launch-keys:<userID>`, owner the launch
+//   id) before the launch is stored. The same key with an equivalent body returns the existing launch (even an
+//   ended one, until it is pruned); a different body is invalid with a hint. A claim whose launch never appeared
+//   (its creator crashed) blocks the key for RESERVATION_MS, then is taken over.
+// - Pruning: ended launches older than endedKeepMs, and all but the newest endedMax ended ones, are removed and
+//   their keys released. Live launches are never pruned.
+import { randomBytes } from "node:crypto"
+import type { Clock, StateStore } from "../backend/types"
+import { AgentError } from "./errors"
+import { type LaunchSpec, launchBodyKey } from "./launch-spec"
+import { updateVersioned } from "./versioned"
+
+export const LAUNCHES = "launches"
+export const REASON_MAX = 500
+export const HISTORY_MAX = 20
+export const ENDED_KEEP_MS = 7 * 86_400_000
+export const ENDED_MAX = 500
+/** How long a key claim without its launch (a creator that may still be writing) blocks the key. */
+export const RESERVATION_MS = 60_000
+/** Reads of a key holder's launch: its creator may be between the claim and the write, so a miss is re-read. */
+const READS = 5
+/** Claim attempts (a stale claim is taken over between them). */
+const CLAIMS = 3
+
+export const LAUNCH_STATES = ["queued", "placing", "provisioning", "running", "ended"] as const
+export type LaunchState = (typeof LAUNCH_STATES)[number]
+export const LAUNCH_OUTCOMES = ["idle", "needs_user", "failed", "timeout", "stopped", "lost"] as const
+export type LaunchOutcome = (typeof LAUNCH_OUTCOMES)[number]
+
+/** The states each state may move to. */
+const NEXT: Record<LaunchState, readonly LaunchState[]> = {
+  queued: ["placing", "ended"],
+  placing: ["provisioning", "queued", "ended"],
+  provisioning: ["running", "ended"],
+  running: ["ended"],
+  ended: [],
+}
+
+export interface LaunchStep {
+  readonly state: LaunchState
+  readonly reason: string
+  readonly at: number
+  readonly outcome?: LaunchOutcome
+}
+
+export interface Launch {
+  readonly id: string
+  /** The user it belongs to. */
+  readonly owner: string
+  readonly spec: LaunchSpec
+  /** Who launched it, as the caller describes them (e.g. `app:<token id>`, `ses_…`, `user`). */
+  readonly by?: string
+  readonly state: LaunchState
+  readonly reason: string
+  /** When it entered its state. */
+  readonly at: number
+  readonly outcome?: LaunchOutcome
+  readonly machineID?: string
+  readonly sessionID?: string
+  readonly name?: string
+  readonly artifacts?: Readonly<Record<string, unknown>>
+  readonly created: number
+  readonly history: readonly LaunchStep[]
+}
+
+export interface TransitionInput {
+  readonly reason: string
+  readonly outcome?: LaunchOutcome
+  readonly machineID?: string
+  readonly sessionID?: string
+  readonly name?: string
+  readonly artifacts?: Readonly<Record<string, unknown>>
+  /** Apply only when the launch is in one of these states (else LaunchTransitionError). */
+  readonly from?: readonly LaunchState[]
+}
+
+export interface LaunchFilter {
+  /** Every label must match the spec's. */
+  readonly labels?: Readonly<Record<string, string>>
+  readonly states?: readonly LaunchState[]
+}
+
+export interface LaunchStoreDeps {
+  readonly state: StateStore
+  readonly now?: Clock
+  readonly newID?: () => string
+  readonly endedKeepMs?: number
+  readonly endedMax?: number
+}
+
+/** A step the state machine does not allow (or not from the current state); the launch is unchanged. */
+export class LaunchTransitionError extends AgentError {
+  constructor(
+    readonly from: LaunchState,
+    readonly to: LaunchState,
+  ) {
+    super(from === "ended" ? "gone" : "invalid", from === "ended" ? "The launch already ended" : `A launch cannot go from ${from} to ${to}`)
+    this.name = "LaunchTransitionError"
+  }
+}
+
+/** Control characters become spaces; trimmed and bounded. */
+const cleanReason = (reason: unknown): string => {
+  const text = typeof reason === "string" ? reason.replace(/[\u0000-\u001f\u007f-\u009f]+/g, " ").trim().slice(0, REASON_MAX).trim() : ""
+  if (!text) throw new Error("A launch transition needs a reason")
+  return text
+}
+
+/** The first step (how it began) and the latest ones. */
+const bounded = (history: readonly LaunchStep[]): LaunchStep[] =>
+  history.length <= HISTORY_MAX ? [...history] : [history[0]!, ...history.slice(history.length - HISTORY_MAX + 1)]
+
+const byCreation = (a: Launch, b: Launch) => a.created - b.created || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)
+
+export class LaunchStore {
+  private readonly now: Clock
+  private readonly newID: () => string
+  private readonly endedKeepMs: number
+  private readonly endedMax: number
+
+  constructor(private readonly deps: LaunchStoreDeps) {
+    this.now = deps.now ?? Date.now
+    this.newID = deps.newID ?? (() => `l_${randomBytes(8).toString("hex")}`)
+    this.endedKeepMs = deps.endedKeepMs ?? ENDED_KEEP_MS
+    this.endedMax = deps.endedMax ?? ENDED_MAX
+  }
+
+  /**
+   * Stores a new queued launch, or (same key, equivalent body) returns the existing one with created false.
+   * Throws invalid (key reused with another body) or rate_limited (the key's launch is still being created).
+   */
+  async create(userID: string, spec: LaunchSpec, options: { readonly by?: string } = {}): Promise<{ launch: Launch; created: boolean }> {
+    const id = this.newID()
+    if (spec.key !== undefined) {
+      const existing = await this.claimKey(userID, spec.key, id)
+      if (existing) {
+        if (launchBodyKey(existing.spec) !== launchBodyKey(spec)) {
+          throw new AgentError("invalid", `Launch key ${spec.key} was used for a different launch (${existing.id})`, {
+            hint: "Use a new key for a different launch, or resend the original body to get that launch",
+          })
+        }
+        return { launch: existing, created: false }
+      }
+    }
+    const at = this.now()
+    const launch: Launch = {
+      id,
+      owner: userID,
+      spec,
+      ...(options.by !== undefined ? { by: options.by } : {}),
+      state: "queued",
+      reason: "Queued",
+      at,
+      created: at,
+      history: [{ state: "queued", reason: "Queued", at }],
+    }
+    const written = await this.deps.state.put(userID, LAUNCHES, id, launch, { ifVersion: 0 })
+    if (!written.ok) throw new Error(`launch id ${id} already exists`)
+    return { launch, created: true }
+  }
+
+  async get(userID: string, id: string): Promise<Launch | undefined> {
+    return (await this.deps.state.get<Launch>(userID, LAUNCHES, id))?.value
+  }
+
+  /** The user's launches by creation, filtered. */
+  async list(userID: string, filter: LaunchFilter = {}): Promise<Launch[]> {
+    const launches = (await this.deps.state.list<Launch>(userID, LAUNCHES)).map((entry) => entry.value)
+    return launches
+      .filter((launch) => !filter.states || filter.states.includes(launch.state))
+      .filter((launch) => !filter.labels || Object.entries(filter.labels).every(([key, value]) => launch.spec.labels[key] === value))
+      .sort(byCreation)
+  }
+
+  /** Moves the launch to `to`; throws not_found, LaunchTransitionError, or Error for a malformed step. */
+  async transition(userID: string, id: string, to: LaunchState, input: TransitionInput): Promise<Launch> {
+    const reason = cleanReason(input.reason)
+    const at = this.now()
+    const next = await updateVersioned<Launch>(this.deps.state, userID, LAUNCHES, id, (current) => {
+      if (!current) throw new AgentError("not_found", `No launch ${id}`)
+      if (!NEXT[current.state].includes(to) || (input.from && !input.from.includes(current.state))) throw new LaunchTransitionError(current.state, to)
+      checkDetails(to, input)
+      const step: LaunchStep = { state: to, reason, at, ...(input.outcome !== undefined ? { outcome: input.outcome } : {}) }
+      return {
+        ...current,
+        state: to,
+        reason,
+        at,
+        ...(input.outcome !== undefined ? { outcome: input.outcome } : {}),
+        ...(input.machineID !== undefined ? { machineID: input.machineID } : {}),
+        ...(input.sessionID !== undefined ? { sessionID: input.sessionID } : {}),
+        ...(input.name !== undefined ? { name: input.name } : {}),
+        ...(input.artifacts !== undefined ? { artifacts: input.artifacts } : {}),
+        history: bounded([...current.history, step]),
+      }
+    })
+    return next!
+  }
+
+  /** Removes ended launches past endedKeepMs or beyond the newest endedMax; resolves with the removed ids. */
+  async prune(userID: string): Promise<string[]> {
+    const { state } = this.deps
+    const ended = (await state.list<Launch>(userID, LAUNCHES)).filter((entry) => entry.value.state === "ended")
+    ended.sort((a, b) => b.value.at - a.value.at || byCreation(b.value, a.value))
+    const cutoff = this.now() - this.endedKeepMs
+    const removed: string[] = []
+    for (const [index, entry] of ended.entries()) {
+      if (index < this.endedMax && entry.value.at > cutoff) continue
+      const deleted = await state.delete(userID, LAUNCHES, entry.key, { ifVersion: entry.version })
+      if (!deleted.ok) continue
+      if (entry.value.spec.key !== undefined) await state.release(keyNamespace(userID), entry.value.spec.key, entry.value.id)
+      removed.push(entry.value.id)
+    }
+    return removed
+  }
+
+  // ---- internals ----------------------------------------------------------------------------------------
+
+  private async launchOf(userID: string, id: string): Promise<Launch | undefined> {
+    for (let read = 0; read < READS; read++) {
+      const launch = await this.get(userID, id)
+      if (launch) return launch
+    }
+    return undefined
+  }
+
+  /** Claims the key for `id`: undefined when claimed (create it), else the launch that holds it. */
+  private async claimKey(userID: string, key: string, id: string): Promise<Launch | undefined> {
+    const { state } = this.deps
+    const namespace = keyNamespace(userID)
+    for (let attempt = 0; attempt < CLAIMS; attempt++) {
+      const claimed = await state.claim(namespace, key, id)
+      if (claimed.ok) return undefined
+      const holder = claimed.conflict
+      const existing = await this.launchOf(userID, holder.owner)
+      if (existing) return existing
+      if (this.now() - holder.at < RESERVATION_MS) {
+        throw new AgentError("rate_limited", `Launch key ${key} is being created`, { extra: { retryAfter: 1 } })
+      }
+      // Its creator crashed between the claim and the write: take the key over.
+      await state.release(namespace, key, holder.owner)
+    }
+    throw new AgentError("rate_limited", `Launch key ${key} is contended`, { extra: { retryAfter: 1 } })
+  }
+}
+
+const keyNamespace = (userID: string) => `launch-keys:${userID}`
+
+function checkDetails(to: LaunchState, input: TransitionInput): void {
+  if (to === "ended") {
+    if (!LAUNCH_OUTCOMES.includes(input.outcome as LaunchOutcome)) throw new Error(`Ending a launch needs an outcome: ${LAUNCH_OUTCOMES.join(", ")}`)
+  } else if (input.outcome !== undefined) throw new Error("Only an ended launch has an outcome")
+  if (to === "provisioning" && !input.machineID) throw new Error("Provisioning a launch needs its machine")
+  if (to === "running" && !input.sessionID) throw new Error("A running launch needs its session")
+}

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

@@ -0,0 +1,206 @@
+// Launch-bound tokens (phase 5, decision #6): the credential a harness inside a sandbox (OpenShell) uses to
+// connect back to /spoke/ws for exactly one launch. The node passes it into the sandbox it provisions; it is
+// accepted only while that launch is provisioning or running.
+//
+// Format: `hlt1.<b64url(payload JSON)>.<b64url(HMAC-SHA256(secret of kid, "hlt1." + payload part))>`, where the
+// payload is {uid, mid, lid, exp (ms since the epoch), kid, ue (user epoch), me (machine epoch), aud (the hub's
+// public URL)}. Signed with the same TokenKeys as session tokens (hst1); the prefix is part of the signed text,
+// so neither kind can pass for the other.
+//
+// The verifier depends only on a LaunchLookup (state and machine of a user's launch), not on the launch engine;
+// LaunchStore fits it as `{ launch: (userID, launchID) => launchStore.get(userID, launchID) }`. Holding a valid
+// token is all this module checks: one connection per launch, and keeping launch-bound connections out of
+// serviceFor/exposeTarget/launchService, are /spoke/ws's and the registry's job.
+// Tokens and secrets are never logged and never appear in this object's JSON or inspect output.
+import { createHmac, timingSafeEqual } from "node:crypto"
+import type { Store } from "../store"
+import type { TokenKeys } from "../token-keys"
+import type { LaunchState } from "./launch-store"
+
+export const LAUNCH_TOKEN_PREFIX = "hlt1"
+/** How long a launch token is valid. */
+export const LAUNCH_TOKEN_LIFETIME_MS = 24 * 60 * 60 * 1000
+/** Longest launch token accepted (the same bound as session tokens). */
+export const LAUNCH_TOKEN_MAX_CHARS = 4096
+/** The launch states in which a launch token is minted and accepted. */
+export const LAUNCH_TOKEN_STATES: readonly LaunchState[] = ["provisioning", "running"]
+
+/** What the tokens need to know about a launch (implemented by the launch store). */
+export interface LaunchView {
+  readonly state: LaunchState
+  /** The machine (node) it is placed on. */
+  readonly machineID?: string
+}
+
+/** Looks up a user's launch (undefined when the user has no such launch). */
+export interface LaunchLookup {
+  launch(userID: string, launchID: string): Promise<LaunchView | undefined> | LaunchView | undefined
+}
+
+export interface LaunchTokensOptions {
+  readonly keys: TokenKeys
+  readonly store: Store
+  readonly launches: LaunchLookup
+  /** The hub's public URL: the tokens' audience. */
+  readonly publicURL: string
+  readonly now?: () => number
+  readonly lifetimeMs?: number
+}
+
+export interface MintedLaunchToken {
+  readonly token: string
+  /** Expiry, ms since the epoch. */
+  readonly exp: number
+}
+
+/** What a valid launch token is bound to. */
+export interface LaunchBinding {
+  readonly userID: string
+  readonly machineID: string
+  readonly launchID: string
+  /** The token's expiry, ms since the epoch. */
+  readonly exp: number
+}
+
+/** The binding of a valid token, "expired" for a genuine token past its expiry, else undefined. */
+export type LaunchVerifyResult = LaunchBinding | "expired" | undefined
+
+interface Claims {
+  readonly uid: string
+  readonly mid: string
+  readonly lid: string
+  readonly exp: number
+  readonly kid: string
+  readonly ue: number
+  readonly me: number
+  readonly aud: string
+}
+
+const CLAIM_KEYS = ["uid", "mid", "lid", "exp", "kid", "ue", "me", "aud"].sort().join()
+const B64URL = /^[A-Za-z0-9_-]+$/
+/** HMAC-SHA256 output length. */
+const SIG_BYTES = 32
+
+const text = (v: unknown): v is string => typeof v === "string" && v.length > 0
+const count = (v: unknown): v is number => typeof v === "number" && Number.isSafeInteger(v) && v >= 0
+
+/** Canonical base64url only (no padding, no other alphabet, no non-zero trailing bits). */
+function decode(part: string): Buffer | undefined {
+  if (!B64URL.test(part)) return undefined
+  const bytes = Buffer.from(part, "base64url")
+  return bytes.toString("base64url") === part ? bytes : undefined
+}
+
+function parseClaims(bytes: Buffer): Claims | undefined {
+  let raw: unknown
+  try {
+    raw = JSON.parse(bytes.toString("utf8"))
+  } catch {
+    return undefined
+  }
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return undefined
+  const c = raw as Record<string, unknown>
+  if (Object.keys(c).sort().join() !== CLAIM_KEYS) return undefined
+  if (!text(c.uid) || !text(c.mid) || !text(c.lid) || !text(c.kid) || !text(c.aud)) return undefined
+  if (!count(c.exp) || !count(c.ue) || !count(c.me)) return undefined
+  return c as unknown as Claims
+}
+
+const sign = (secret: Buffer, payload: string): Buffer => createHmac("sha256", secret).update(`${LAUNCH_TOKEN_PREFIX}.${payload}`).digest()
+
+export class LaunchTokens {
+  readonly lifetimeMs: number
+  readonly #keys: TokenKeys
+  readonly #store: Store
+  readonly #launches: LaunchLookup
+  readonly #aud: string
+  readonly #now: () => number
+
+  constructor(options: LaunchTokensOptions) {
+    this.#keys = options.keys
+    this.#store = options.store
+    this.#launches = options.launches
+    this.#aud = options.publicURL
+    this.#now = options.now ?? Date.now
+    this.lifetimeMs = options.lifetimeMs ?? LAUNCH_TOKEN_LIFETIME_MS
+  }
+
+  /** The owner of an enrolled, unrevoked machine whose user exists and is enabled. */
+  #owner(machineID: string): string | undefined {
+    const machine = this.#store.machines().find((m) => m.id === machineID)
+    if (!machine || machine.revoked) return undefined
+    const user = this.#store.user(machine.ownerID)
+    return user && !user.disabled ? user.id : undefined
+  }
+
+  /** Whether the user's launch is provisioning or running on the machine (false when the lookup fails). */
+  async #live(userID: string, launchID: string, machineID: string): Promise<boolean> {
+    let launch: LaunchView | undefined
+    try {
+      launch = await this.#launches.launch(userID, launchID)
+    } catch {
+      return false
+    }
+    return launch !== undefined && LAUNCH_TOKEN_STATES.includes(launch.state) && launch.machineID === machineID
+  }
+
+  /**
+   * A token for a launch of the machine's owner that is provisioning or running on that machine (undefined when
+   * the machine is unknown, revoked or its owner disabled, or the launch is someone else's, elsewhere or not live).
+   */
+  async mint(machineID: string, launchID: string): Promise<MintedLaunchToken | undefined> {
+    const uid = this.#owner(machineID)
+    if (!uid || !(await this.#live(uid, launchID, machineID))) return undefined
+    const { kid, secret } = this.#keys.active()
+    const exp = this.#now() + this.lifetimeMs
+    const claims: Claims = {
+      uid,
+      mid: machineID,
+      lid: launchID,
+      exp,
+      kid,
+      ue: this.#store.userEpoch(uid),
+      me: this.#store.machineEpoch(machineID),
+      aud: this.#aud,
+    }
+    const payload = Buffer.from(JSON.stringify(claims)).toString("base64url")
+    return { token: `${LAUNCH_TOKEN_PREFIX}.${payload}.${sign(secret, payload).toString("base64url")}`, exp }
+  }
+
+  /**
+   * What a token is bound to while all of this holds: signature (constant-time) under a known kid, audience,
+   * expiry, the user's and machine's current token epochs, the machine exists, is not revoked and belongs to uid,
+   * the user exists and is enabled, and uid's launch is provisioning or running on that machine.
+   */
+  async verify(token: string): Promise<LaunchVerifyResult> {
+    if (typeof token !== "string" || token.length > LAUNCH_TOKEN_MAX_CHARS) return undefined
+    const parts = token.split(".")
+    if (parts.length !== 3 || parts[0] !== LAUNCH_TOKEN_PREFIX) return undefined
+    const [, payload, sigPart] = parts as [string, string, string]
+    const body = decode(payload)
+    const sig = decode(sigPart)
+    if (!body || !sig || sig.length !== SIG_BYTES) return undefined
+    const claims = parseClaims(body)
+    if (!claims) return undefined
+    const secret = this.#keys.key(claims.kid)
+    if (!secret) return undefined
+    const expected = sign(secret, payload)
+    if (expected.length !== sig.length || !timingSafeEqual(expected, sig)) return undefined
+    if (claims.aud !== this.#aud) return undefined
+    if (this.#now() >= claims.exp) return "expired"
+    // A shared store reads the user and machine again first (revocations and epoch bumps on other pods).
+    await this.#store.recheck({ users: [claims.uid], machines: [claims.mid] })
+    if (claims.ue !== this.#store.userEpoch(claims.uid) || claims.me !== this.#store.machineEpoch(claims.mid)) return undefined
+    if (this.#owner(claims.mid) !== claims.uid) return undefined
+    if (!(await this.#live(claims.uid, claims.lid, claims.mid))) return undefined
+    return { userID: claims.uid, machineID: claims.mid, launchID: claims.lid, exp: claims.exp }
+  }
+
+  toJSON(): { audience: string; lifetimeMs: number } {
+    return { audience: this.#aud, lifetimeMs: this.lifetimeMs }
+  }
+
+  [Symbol.for("nodejs.util.inspect.custom")](): string {
+    return `LaunchTokens(${this.#aud})`
+  }
+}

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

@@ -0,0 +1,123 @@
+// Loop protection for agent messages (design §3.4), over the backend interfaces with an injected clock.
+//
+// - HopTracker: every message carries a hop. A session's (or app's) depth is the deepest hop that reached it
+//   since its last human turn; what it sends carries depth + 1. The user sends hop 0, and a hop-0 message (or a
+//   human turn in the session) resets the depth. A hop over HOP_CAP is delivered without waking and the user
+//   is alerted (the delivery engine does both).
+// - MessageLimiter: fixed windows aligned to the clock (so retryAfter is exact): messages per sender→recipient
+//   pair and per user (refused with rate_limited), and wakes per recipient (exhausted: deliver without waking).
+import type { Clock, Counters, StateStore } from "../backend/types"
+import { type Party, partyKey } from "./envelope"
+import { AgentError } from "./errors"
+import { updateVersioned } from "./versioned"
+
+/** Hops a reply chain may take without a human turn. */
+export const HOP_CAP = 8
+/** A depth no message refreshed for this long is forgotten. */
+export const HOP_TTL_MS = 24 * 60 * 60_000
+
+export const overHopCap = (hop: number): boolean => hop > HOP_CAP
+
+/** StateStore collection: partyKey → HopDepth. */
+const HOPS = "message-hops"
+
+interface HopDepth {
+  readonly depth: number
+  readonly at: number
+}
+
+export class HopTracker {
+  private readonly state: StateStore
+  private readonly now: Clock
+
+  constructor(deps: { readonly state: StateStore; readonly now?: Clock }) {
+    this.state = deps.state
+    this.now = deps.now ?? Date.now
+  }
+
+  /** The hop a new message from `from` carries. */
+  async next(userID: string, from: Party): Promise<number> {
+    return from.kind === "user" ? 0 : (await this.depth(userID, from)) + 1
+  }
+
+  /** The deepest hop that reached the party since its last human turn (0: none, or forgotten). */
+  async depth(userID: string, party: Party): Promise<number> {
+    return this.live((await this.state.get<HopDepth>(userID, HOPS, partyKey(party)))?.value)
+  }
+
+  /** A message with `hop` reached the party. */
+  async received(userID: string, to: Party, hop: number): Promise<void> {
+    if (to.kind === "user") return
+    const at = this.now()
+    await updateVersioned<HopDepth>(this.state, userID, HOPS, partyKey(to), (current) => ({ depth: hop === 0 ? 0 : Math.max(this.live(current), hop), at }))
+  }
+
+  /** A human turn in the session (console prompt, voice, typed in the harness): the chain starts over. */
+  async humanTurn(userID: string, sessionID: string): Promise<void> {
+    await this.state.delete(userID, HOPS, partyKey({ kind: "session", sessionID }))
+  }
+
+  private live(entry: HopDepth | undefined): number {
+    return entry && this.now() - entry.at < HOP_TTL_MS ? entry.depth : 0
+  }
+}
+
+/** The length of every limiter window. */
+export const WINDOW_MS = 10 * 60_000
+/** Messages per sender→recipient pair per window. */
+export const PAIR_LIMIT = 20
+/** Messages per user per window, across all pairs. */
+export const USER_LIMIT = 300
+/** Wakes per recipient per window. */
+export const WAKE_BUDGET = 30
+
+export interface MessageLimits {
+  readonly pair: number
+  readonly user: number
+  readonly wake: number
+}
+
+export class MessageLimiter {
+  private readonly counters: Counters
+  private readonly now: Clock
+  private readonly limits: MessageLimits
+
+  constructor(deps: { readonly counters: Counters; readonly now?: Clock; readonly limits?: Partial<MessageLimits> }) {
+    this.counters = deps.counters
+    this.now = deps.now ?? Date.now
+    this.limits = { pair: PAIR_LIMIT, user: USER_LIMIT, wake: WAKE_BUDGET, ...deps.limits }
+  }
+
+  /** Counts a message from → to; throws rate_limited ({retryAfter, limit}) when a cap is reached (not counted). */
+  async admit(userID: string, from: Party, to: Party): Promise<void> {
+    const window = this.window()
+    const keys = [
+      { limit: "pair" as const, key: `msg:pair:${userID}:${partyKey(from)}:${partyKey(to)}:${window.index}`, max: this.limits.pair },
+      { limit: "user" as const, key: `msg:user:${userID}:${window.index}`, max: this.limits.user },
+    ]
+    for (const { limit, key, max } of keys) {
+      if ((await this.counters.get(key)) >= max) {
+        throw new AgentError("rate_limited", `Too many messages (${limit} limit)`, {
+          hint: "Wait and try again",
+          extra: { retryAfter: Math.ceil(window.remaining / 1000), limit },
+        })
+      }
+    }
+    for (const { key } of keys) await this.counters.incr(key, window.remaining)
+  }
+
+  /** Uses one of the recipient's wakes; false when the budget is spent (deliver without waking). */
+  async wake(userID: string, to: Party): Promise<boolean> {
+    const window = this.window()
+    const key = `msg:wake:${userID}:${partyKey(to)}:${window.index}`
+    if ((await this.counters.get(key)) >= this.limits.wake) return false
+    await this.counters.incr(key, window.remaining)
+    return true
+  }
+
+  private window(): { index: number; remaining: number } {
+    const t = this.now()
+    const index = Math.floor(t / WINDOW_MS)
+    return { index, remaining: (index + 1) * WINDOW_MS - t }
+  }
+}