@huynle/hub 0.8.6 → 0.9.0

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

@@ -1,8 +1,8 @@
 // Messaging on /api/agent (design §3, §8; decisions jswt9p22): thin routes over the delivery engine (./delivery).
 //
 // Routes (user actors always; session tokens; app tokens by scope):
-//   POST /api/agent/msg      {to, text, wake?, urgent?, all?}              messages:send → 201 {message, delivery?} | {sent: [...]} (all)
-//   POST /api/agent/ask      {to, text, wake?, urgent?, all?, expiresIn?, wait?}  messages:send → 201 {message, delivery?, answer?}
+//   POST /api/agent/msg      {to, text, wake?, urgent?, all?, notAfter?}   messages:send → 201 {message, delivery?} | {sent: [...]} (all)
+//   POST /api/agent/ask      {to, text, wake?, urgent?, all?, expiresIn?, notAfter?, wait?}  messages:send → 201 {message, delivery?, answer?}
 //   POST /api/agent/reply    {replyTo, text, wake?}                        messages:send → 201 {message, delivery?, original}
 //   POST /api/agent/decline  {replyTo, why}                                messages:send → 201 {message, delivery?, original}
 //   GET  /api/agent/inbox                                                  messages:read → {asks, waiting, messages, muted}
@@ -23,9 +23,19 @@
 // - expiresIn and wait are seconds. wait (0–WAIT_MAX_S) long-polls an ask until it is answered, declined or
 //   expired; longer waits loop on GET /messages/:id?wait=. A message reads for its sender and recipient (and the
 //   user, who owns every party); others get not_found.
+// - notAfter (H2, ./not-after): don't deliver after this time, in epoch milliseconds (an integer, at most 30 days
+//   ahead, else invalid). Already passed at submit → 422 expired, and nothing is stored, delivered or pushed. A
+//   message pending for an offline session expires at min(24 h, notAfter) (message.changed carries reason
+//   not_after | pending_timeout); an ask expires at min(expiresIn, notAfter); @me is checked at submit only.
 // - Messaging off (UserRecord.agent.messagingPaused): msg, ask, reply and decline answer paused; reading works.
 // - Every stored message is published on the MessageFeed (GET /api/agent/watch 'message' events, waiters).
+// - Idempotency-Key (H1, pd2e6df8) on msg and ask, per sender (the user, an app token, a session): the same key
+//   and body again within IDEMPOTENCY_TTL_MS answer 200 with the original body ({message, delivery?}, {sent} with
+//   all, {message, decision, …} for ask @me) and `idempotent-replayed: true`, sending, pushing and opening
+//   nothing; another body is 409 conflict, as is a repeat while the first still runs; a malformed key 400 invalid.
+//   Records live in the StateStore (MESSAGE_IDEMPOTENCY; ./idempotency), so they survive a restart.
 import { boundedJson } from "./body"
+import type { Clock, StateStore } from "../backend/types"
 import { Feed } from "../cluster/feed"
 import type { Store } from "../store"
 import type { AgentActor } from "./actor"
@@ -34,14 +44,18 @@ import type { Delivery, SendOptions, Sent } from "./delivery"
 import type { Directory } from "./directory"
 import { partyFromActor, partyKey } from "./envelope"
 import { AgentError } from "./errors"
+import { idempotencyKeyOf, REPLAYED_HEADER, RouteIdempotency } from "./idempotency"
 import { TEXT_MAX, WHY_MAX, type Message } from "./messages"
-import { AGENT_PREFIX, type AgentRoute } from "./routes"
+import { AGENT_PREFIX, type AgentContext, type AgentRoute } from "./routes"
 
 /** The longest wait of one request (seconds); clients loop for longer ones. */
 export const WAIT_MAX_S = 60
 /** How often a waiting request looks at the message besides the feed (expiry, other hub processes). */
 export const WAIT_POLL_MS = 1_000
 
+/** The StateStore collection of msg/ask Idempotency-Key records (./idempotency). */
+export const MESSAGE_IDEMPOTENCY = "message-idempotency"
+
 /** Message events' Bus topic (cluster mode). */
 export const MESSAGES_TOPIC = "feed.messages"
 
@@ -61,6 +75,9 @@ export interface MessageDeps {
   readonly decisions?: Decisions
   /** Default WAIT_POLL_MS. */
   readonly pollMs?: number
+  /** Where msg/ask keep their Idempotency-Key records; without it a key is checked for shape but not remembered. */
+  readonly state?: StateStore
+  readonly now?: Clock
 }
 
 const NO_STORE = { "cache-control": "no-store" }
@@ -105,10 +122,12 @@ function waitQuery(raw: string | null): number | undefined {
   return seconds(/^\d+(\.\d+)?$/.test(raw) ? Number(raw) : Number.NaN, "wait", WAIT_MAX_S)
 }
 
-const sendOptions = (body: Body): SendOptions => {
+const sendOptions = (body: Body, delivery: Pick<Delivery, "checkNotAfter">): SendOptions => {
   const wake = flag(body, "wake")
   const urgent = flag(body, "urgent")
-  return { ...(wake === undefined ? {} : { wake }), ...(urgent === undefined ? {} : { urgent }) }
+  // Checked against the engine's clock here too, so an ask to @me (a Decision, not sent through send()) is refused.
+  const notAfter = body.notAfter === undefined ? undefined : delivery.checkNotAfter(body.notAfter)
+  return { ...(wake === undefined ? {} : { wake }), ...(urgent === undefined ? {} : { urgent }), ...(notAfter === undefined ? {} : { notAfter }) }
 }
 
 /** The user's address (also the malformed `@me.project`, which the delivery engine refuses). */
@@ -165,6 +184,25 @@ const sentView = ({ message, delivery, woke, wakeSkipped }: Sent) => ({
 export function messageRoutes(deps: MessageDeps): AgentRoute[] {
   const { delivery, feed } = deps
   const pollMs = deps.pollMs ?? WAIT_POLL_MS
+  const idempotency = deps.state ? new RouteIdempotency({ state: deps.state, collection: MESSAGE_IDEMPOTENCY, ...(deps.now ? { now: deps.now } : {}) }) : undefined
+
+  /**
+   * A send handler run once per (sender, route, Idempotency-Key, body): a repeat answers 200 with the original body
+   * and `idempotent-replayed: true`, and sends nothing. Without the header the handler simply runs.
+   */
+  const once =
+    (handle: (context: AgentContext) => Promise<Response>) =>
+    async (context: AgentContext): Promise<Response> => {
+      const key = idempotencyKeyOf(context.request)
+      if (key === undefined || !idempotency) return handle(context)
+      const body = await bodyOf(context.request.clone())
+      const route = `POST ${context.url.pathname} ${partyKey(partyFromActor(context.actor))}`
+      const response = await idempotency.run(context.user.id, route, key, body, async () => {
+        const answer = await handle(context)
+        return { status: answer.status, body: await answer.json() }
+      })
+      return response.headers.get(REPLAYED_HEADER) ? new Response(response.body, { status: 200, headers: response.headers }) : response
+    }
 
   const paused = (userID: string) => deps.store.agentData(userID).messagingPaused === true
   const ensureOn = (userID: string) => {
@@ -235,20 +273,20 @@ export function messageRoutes(deps: MessageDeps): AgentRoute[] {
       method: "POST",
       path: `${AGENT_PREFIX}/msg`,
       allow: SEND,
-      async handle({ request, user, actor }) {
+      handle: once(async ({ request, user, actor }) => {
         const body = await bodyOf(request)
         const to = string(body, "to")
         const text = string(body, "text", TEXT_MAX)
         const all = flag(body, "all")
-        const sent = await send(user.id, actor, to, "msg", text, sendOptions(body), all)
+        const sent = await send(user.id, actor, to, "msg", text, sendOptions(body, delivery), all)
         return ok(all ? { sent: sent.map(sentView) } : sentView(sent[0]!), 201)
-      },
+      }),
     },
     {
       method: "POST",
       path: `${AGENT_PREFIX}/ask`,
       allow: SEND,
-      async handle({ request, user, actor }) {
+      handle: once(async ({ request, user, actor }) => {
         const body = await bodyOf(request)
         const to = string(body, "to")
         const text = string(body, "text", TEXT_MAX)
@@ -256,7 +294,7 @@ export function messageRoutes(deps: MessageDeps): AgentRoute[] {
         const expiresIn = seconds(body.expiresIn, "expiresIn")
         const wait = seconds(body.wait, "wait", WAIT_MAX_S)
         if (all && wait !== undefined) throw new AgentError("invalid", "wait cannot be combined with all")
-        const options: SendOptions = { ...sendOptions(body), ...(expiresIn === undefined ? {} : { expiresInMs: Math.round(expiresIn * 1000) }) }
+        const options: SendOptions = { ...sendOptions(body, delivery), ...(expiresIn === undefined ? {} : { expiresInMs: Math.round(expiresIn * 1000) }) }
         const decisionAsked = DECISION_FIELDS.some((key) => body[key] !== undefined)
         if (isMe(to) && deps.decisions) {
           if (all) throw new AgentError("invalid", "all cannot be combined with @me")
@@ -277,7 +315,7 @@ export function messageRoutes(deps: MessageDeps): AgentRoute[] {
         const sent = await send(user.id, actor, to, "ask", text, options, all)
         if (all) return ok({ sent: sent.map(sentView) }, 201)
         return ok({ ...sentView(sent[0]!), ...(await settled(user.id, sent[0]!.message, wait, request.signal)) }, 201)
-      },
+      }),
     },
     {
       method: "POST",

package/src/central/agent/messages.ts

@@ -2,7 +2,7 @@
 // the message routes (P2-T6) and the delivery engine (P2-T5) call it.
 //
 // - Stored form: {id, kind, from, to, recipient, generation?, text, replyTo?, state, at, hop, expiresAt?,
-//   delivery?, deliveredAt?, answer?}. `from` is the authenticated sender (partyFromActor); `to` keeps the
+//   notAfter?, delivery?, expiredReason?, deliveredAt?, answer?}. `from` is the authenticated sender (partyFromActor); `to` keeps the
 //   address as written (`@@reviewer`), `recipient` the party it reached; text and `to` are sanitised.
 // - Caps: each party (session, the user, an app) keeps its latest SESSION_MESSAGES; a message no party keeps
 //   is deleted. Per user, at most USER_MESSAGES messages / USER_BYTES; over either, the oldest go (down to
@@ -17,6 +17,7 @@ import { randomBytes } from "node:crypto"
 import type { Clock, StateStore } from "../backend/types"
 import { type Party, partyKey, sanitizeLabel, sanitizeText } from "./envelope"
 import { AgentError } from "./errors"
+import type { ExpiredReason } from "./not-after"
 import { updateVersioned } from "./versioned"
 
 /** Messages each party keeps. */
@@ -66,7 +67,11 @@ export interface Message {
   readonly hop: number
   /** Asks only. */
   readonly expiresAt?: number
+  /** Not delivered after this (epoch ms; ./not-after): a pending hold ends then, and an ask expires by then. */
+  readonly notAfter?: number
   readonly delivery?: Delivery
+  /** delivery "expired" only: its notAfter passed (not_after), or the 24 h pending hold ran out (pending_timeout). */
+  readonly expiredReason?: ExpiredReason
   /** When it was first delivered (steer, turn or queued). */
   readonly deliveredAt?: number
   /** The reply or decline that closed an ask. */
@@ -90,6 +95,8 @@ export interface SendInput {
   readonly hop?: number
   /** Asks only; default ASK_EXPIRES_MS. */
   readonly expiresInMs?: number
+  /** Validated by the caller (parseNotAfter): stored; an ask expires by then at the latest. */
+  readonly notAfter?: number
 }
 
 export interface AnswerInput {
@@ -224,7 +231,8 @@ export class Messages {
       state: input.kind === "ask" ? "open" : "sent",
       at,
       hop: input.hop ?? 0,
-      ...(input.kind === "ask" ? { expiresAt: at + expiresIn } : {}),
+      ...(input.kind === "ask" ? { expiresAt: Math.min(at + expiresIn, input.notAfter ?? Number.POSITIVE_INFINITY) } : {}),
+      ...(input.notAfter === undefined ? {} : { notAfter: input.notAfter }),
     }
     await this.store(userID, message)
     return message
@@ -286,13 +294,18 @@ export class Messages {
   }
 
   /** Records how the message was delivered; undefined when there is no such message. */
-  async setDelivery(userID: string, id: string, delivery: Delivery): Promise<Message | undefined> {
+  async setDelivery(userID: string, id: string, delivery: Delivery, expiredReason?: ExpiredReason): Promise<Message | undefined> {
     const at = this.now()
     const delivered = delivery === "steer" || delivery === "turn" || delivery === "queued"
     const stored = await updateVersioned<StoredMessage>(this.state, userID, MESSAGES, id, (current) =>
       current && {
         ...current,
-        message: { ...current.message, delivery, ...(current.message.deliveredAt === undefined && delivered ? { deliveredAt: at } : {}) },
+        message: {
+          ...current.message,
+          delivery,
+          ...(current.message.deliveredAt === undefined && delivered ? { deliveredAt: at } : {}),
+          ...(delivery === "expired" && expiredReason ? { expiredReason } : {}),
+        },
       },
     )
     return stored && this.view(stored.message)

package/src/central/agent/not-after.ts

@@ -0,0 +1,28 @@
+// notAfter (H2, gcy04k15): "don't deliver this message after T", a generic app feature. One validator for every
+// surface that takes it (REST msg/ask through the delivery engine; reusable by other senders).
+//
+// - Shape: epoch milliseconds, a finite integer. REST and the SDK take only that; the CLI (--not-after) and MCP
+//   (notAfter) also accept an ISO 8601 date-time and convert it before sending.
+// - At submit: at most NOT_AFTER_MAX_MS ahead (else invalid, 400); already passed (≤ now) → expired (422), and
+//   nothing is stored, delivered or pushed.
+// - Afterwards: a pending hold ends at min(at + PENDING_MS, notAfter); an ask expires at min(expiresIn, notAfter).
+//   An expired delivery records why (ExpiredReason): not_after (the deadline passed) or pending_timeout (24 h hold).
+import { AgentError } from "./errors"
+
+/** The furthest a notAfter may lie ahead of submit time. */
+export const NOT_AFTER_MAX_MS = 30 * 24 * 60 * 60_000
+
+/** Why a pending delivery expired: its notAfter passed, or the 24 h pending hold ran out. */
+export type ExpiredReason = "not_after" | "pending_timeout"
+
+/**
+ * Validates a notAfter at submit time `now` and returns it (undefined when absent). Throws AgentError invalid
+ * (not a finite integer, or more than NOT_AFTER_MAX_MS ahead) or expired (already passed: ≤ now).
+ */
+export function parseNotAfter(value: unknown, now: number): number | undefined {
+  if (value === undefined) return undefined
+  if (typeof value !== "number" || !Number.isSafeInteger(value)) throw new AgentError("invalid", "notAfter must be a time in epoch milliseconds (an integer)")
+  if (value <= now) throw new AgentError("expired", "notAfter has already passed: nothing was sent")
+  if (value > now + NOT_AFTER_MAX_MS) throw new AgentError("invalid", `notAfter must be at most ${NOT_AFTER_MAX_MS / 86_400_000} days from now`)
+  return value
+}

package/src/central/agent/placement.ts

@@ -23,6 +23,9 @@
 //   still takes a node slot. Reservations are
 //   launches provisioning or running on a machine that its node does not report (yet); slots taken in the pass
 //   count at once. Reasons go on the launch only when it moves; waiting reasons are returned for the engine.
+// - notAfter (H3): a queued launch whose notAfter has passed is never placed (checked as the pass reaches it and again
+//   before each placement step, so a node freeing up in the same pass does not take it); it takes no maxActive room
+//   and is returned as expired (left queued or placing) for the engine to end with outcome expired.
 // - PlacementLoop runs passes: kick(user) when something changed (a launch queued or ended, a node connected or
 //   reported capacity, a service spoke came), coalescing kicks during a pass into one more, plus a sweep over
 //   users() every intervalMs for whatever a kick missed (e.g. another process held the lease). Each placed launch
@@ -231,8 +234,13 @@ export interface PassResult {
   readonly leased: boolean
   readonly placed: Placed[]
   readonly waiting: Waiting[]
+  /** (H3) Launches the pass did not place because their notAfter passed (still queued or placing): the engine ends them. */
+  readonly expired?: string[]
 }
 
+/** (H3) The launch's notAfter has passed at `now`: it must not be placed. */
+export const pastNotAfter = (launch: Pick<Launch, "spec">, now: number): boolean => launch.spec.notAfter !== undefined && launch.spec.notAfter <= now
+
 export const placementLeaseKey = (userID: string) => `placement:${userID}`
 
 export class Placement {
@@ -277,9 +285,12 @@ export class Placement {
     const lease = await locks.acquire(key, owner, this.leaseMs)
     const placed: Placed[] = []
     const waiting: Waiting[] = []
-    if (!lease) return { leased: false, placed, waiting }
+    const expired: string[] = []
+    /** The pass's result; expired only when the pass found any. */
+    const result = (leased: boolean, waits: Waiting[]): PassResult => ({ leased, placed, waiting: waits, ...(expired.length > 0 ? { expired } : {}) })
+    if (!lease) return result(false, waiting)
     const held = async () => (await locks.renew(key, owner, this.leaseMs))?.fence === lease.fence
-    const lost = (): PassResult => ({ leased: false, placed, waiting: [] })
+    const lost = (): PassResult => result(false, [])
     try {
       let launches = await store.list(userID)
       // Under the lease, a launch still placing was left by a holder that died mid-pass.
@@ -289,11 +300,15 @@ export class Placement {
       }
       launches = await store.list(userID)
       const queued = launches.filter((l) => l.state === "queued")
-      if (queued.length === 0) return { leased: true, placed, waiting }
+      if (queued.length === 0) return result(true, waiting)
       const counted = launches.filter((l) => ACTIVE.includes(l.state) && !isSystemLaunch(l))
       let active = counted.length
       const candidates = await this.candidates(userID, launches)
       for (const launch of queued) {
+        if (pastNotAfter(launch, this.now())) {
+          expired.push(launch.id)
+          continue
+        }
         const system = isSystemLaunch(launch)
         if (!system && active >= this.caps.maxActive) {
           waiting.push({ launchID: launch.id, wait: "active", ...this.activeReason(userID, counted, launch) })
@@ -306,9 +321,17 @@ export class Placement {
         }
         const name = match.node.name ?? match.node.machineID
         if (!(await held())) return lost()
+        if (pastNotAfter(launch, this.now())) {
+          expired.push(launch.id)
+          continue
+        }
         const placing = await skipGone(store.transition(userID, launch.id, "placing", { reason: `Placing on ${name}`, from: ["queued"] }))
         if (!placing) continue
         if (!(await held())) return lost()
+        if (pastNotAfter(launch, this.now())) {
+          expired.push(launch.id)
+          continue
+        }
         // A stop between the two steps (e.g. the Concierge reaping an orphan) wins: skipped, not an error.
         const provisioning = await skipGone(
           store.transition(userID, launch.id, "provisioning", {
@@ -326,7 +349,7 @@ export class Placement {
         }
         placed.push({ userID, launch: provisioning, node: match.node, preferred: match.preferred, fence: lease.fence })
       }
-      return { leased: true, placed, waiting }
+      return result(true, waiting)
     } finally {
       await locks.release(key, owner)
     }
@@ -392,6 +415,8 @@ export interface PlacementLoopDeps {
   readonly onPlaced: (placed: Placed) => void | Promise<void>
   /** The launches the pass could not place, with why (only for a pass that held the user's lease). */
   readonly onWaiting?: (userID: string, waiting: readonly Waiting[]) => void | Promise<void>
+  /** (H3) The launches a pass did not place because their notAfter passed (the engine ends them expired). */
+  readonly onExpired?: (userID: string, launchIDs: readonly string[]) => void | Promise<void>
   readonly onError?: (cause: unknown, userID?: string) => void
   readonly timers?: Timers
   readonly intervalMs?: number
@@ -484,6 +509,13 @@ export class PlacementLoop {
         this.onError(cause, userID)
       }
     }
+    if (result.expired?.length && this.deps.onExpired) {
+      try {
+        await this.deps.onExpired(userID, result.expired)
+      } catch (cause) {
+        this.onError(cause, userID)
+      }
+    }
     if (!result.leased || !this.deps.onWaiting) return
     try {
       await this.deps.onWaiting(userID, result.waiting)

package/src/central/agent/routes.ts

@@ -103,6 +103,8 @@ export interface AgentDeps {
   readonly delivery?: Delivery
   /** Decisions (ask @me, P2-T9): with the message routes. */
   readonly decisions?: Decisions
+  /** Where msg/ask remember their Idempotency-Key records (survive a restart with the file store). */
+  readonly messageState?: StateStore
   /** The agent audit (P3-T5): GET /api/agent/audit when given. */
   readonly audit?: AgentAudit
   /** Grants (P3-T2): the /api/agent/grants routes when given. */
@@ -206,7 +208,7 @@ export function agentRoutes(deps: AgentDeps): 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.agentEvents && deps.eventCursorKeys ? eventsRoutes({ events: deps.agentEvents, keys: deps.eventCursorKeys, directory: deps.directory, ...eventScope(deps) }) : []),
-    ...(deps.directory && deps.delivery ? messageRoutes({ delivery: deps.delivery, directory: deps.directory, store: deps.store, feed, ...(deps.decisions ? { decisions: deps.decisions } : {}) }) : []),
+    ...(deps.directory && deps.delivery ? messageRoutes({ delivery: deps.delivery, directory: deps.directory, store: deps.store, feed, ...(deps.decisions ? { decisions: deps.decisions } : {}), ...(deps.messageState ? { state: deps.messageState } : {}), ...(deps.now ? { now: deps.now } : {}) }) : []),
     ...(deps.directory && deps.registry ? readRoutes({ store: deps.store, directory: deps.directory, registry: deps.registry, ...(deps.spokes ? { spokes: deps.spokes } : {}), ...launchReads(deps), ...(deps.agentEvents && deps.eventCursorKeys ? { events: { events: deps.agentEvents, keys: deps.eventCursorKeys, directory: deps.directory, ...eventScope(deps) } } : {}), ...(deps.heartbeatMs !== undefined ? { heartbeatMs: deps.heartbeatMs } : {}), ...(deps.now ? { now: deps.now } : {}), ...(deps.draining ? { draining: deps.draining } : {}), ...(deps.teamDiscovery ? { discovery: deps.teamDiscovery } : {}), ...intentReads(deps), ...conciergeReads(deps) }) : []),
     {
       method: "GET",

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

@@ -5,23 +5,28 @@
 //   GET    /api/agent/webhooks/:id    → {webhook, deliveries} (recent deliveries, oldest first)
 //   DELETE /api/agent/webhooks/:id    → 204 (its pending deliveries are dropped)
 //
-// Who: users (all of their registrations, their own and their app tokens'); app tokens with sessions:launch (the
-// scope of the only events so far, launch.*), which see and delete only the registrations they made and get only
-// the events of launches they started. Sessions cannot register webhooks. Another user's registration, or (apps)
-// one the token did not make, is 404 not_found.
+// Who: users (all of their registrations, their own and their app tokens'); app tokens with events:subscribe or
+// teams:submit, which see and delete only the registrations they made. Registering needs, per selected type, its
+// family's scope (webhookRequiredScopes): events:subscribe plus sessions:read / sessions:manage / messages:read /
+// sessions:launch, except that a registration for team.intake alone needs only teams:submit. An app registration gets
+// only the events of what that app caused (its launches, messages it is a party to, intake it submitted). Sessions
+// cannot register webhooks. Another user's registration, or (apps) one the token did not make, is 404 not_found.
 import { boundedJson } from "./body"
 import type { Store } from "../store"
 import type { AgentActor } from "./actor"
 import { AgentError } from "./errors"
 import type { AgentRoute } from "./routes"
-import { webhookEventScopes, type WebhookOwner, type Webhooks } from "./webhooks"
+import { webhookRequiredScopes, type WebhookOwner, type Webhooks } from "./webhooks"
 
 // A literal: routes.ts imports this module.
 const PATH = "/api/agent/webhooks"
 const NO_STORE = { "cache-control": "no-store" }
-/** Users; apps with sessions:launch. */
+/** The scope app tokens need for webhooks of every family but team intake. */
 export const WEBHOOK_SCOPE = "events:subscribe"
-const ALLOW = { scope: WEBHOOK_SCOPE } as const
+/** Any of these lets an app token use the webhook routes (teams:submit: team.intake registrations only). */
+export const WEBHOOK_APP_SCOPES: readonly string[] = [WEBHOOK_SCOPE, "teams:submit"]
+// Users and apps; sessions never. An app's scopes are checked in each handler (routes take one scope).
+const ALLOW = { app: true } as const
 
 export type RouteWebhooks = Pick<Webhooks, "register" | "list" | "get" | "remove" | "deliveries">
 
@@ -30,10 +35,14 @@ const ownerOf = (actor: AgentActor): WebhookOwner | undefined => (actor.kind ===
 
 const notFound = (id: string) => new AgentError("not_found", `No webhook ${id}`)
 
+const requireAppScope = (actor: AgentActor) => {
+  if (actor.kind === "app" && !WEBHOOK_APP_SCOPES.some((scope) => actor.scopes.includes(scope))) throw new AgentError("forbidden", "This credential cannot use this route")
+}
+
 const requireEventScopes = (actor: AgentActor, events: unknown) => {
   if (actor.kind !== "app") return
   const patterns = events === undefined ? ["launch.*"] : Array.isArray(events) && events.every((e) => typeof e === "string") ? events : []
-  const missing = webhookEventScopes(patterns).filter((scope) => !actor.scopes.includes(scope))
+  const missing = webhookRequiredScopes(patterns).filter((scope) => !actor.scopes.includes(scope))
   if (missing.length) throw new AgentError("forbidden", `Webhook events need scope ${missing.join(", ")}`)
 }
 
@@ -50,6 +59,7 @@ export function webhookRoutes(webhooks: RouteWebhooks, store?: Pick<Store, "audi
       path: PATH,
       allow: ALLOW,
       async handle({ request, actor, user }) {
+        requireAppScope(actor)
         const input = await bodyOf(request)
         requireEventScopes(actor, input.events)
         const result = await webhooks.register(user.id, ownerOf(actor) ?? "user", { url: input.url, events: input.events, label: input.label })
@@ -61,13 +71,14 @@ export function webhookRoutes(webhooks: RouteWebhooks, store?: Pick<Store, "audi
       method: "GET",
       path: PATH,
       allow: ALLOW,
-      handle: async ({ actor, user }) => Response.json({ webhooks: await webhooks.list(user.id, ownerOf(actor)) }, { headers: NO_STORE }),
+      handle: async ({ actor, user }) => (requireAppScope(actor), Response.json({ webhooks: await webhooks.list(user.id, ownerOf(actor)) }, { headers: NO_STORE })),
     },
     {
       method: "GET",
       path: `${PATH}/:id`,
       allow: ALLOW,
       async handle({ params, actor, user }) {
+        requireAppScope(actor)
         const webhook = await webhooks.get(user.id, params.id!, ownerOf(actor))
         if (!webhook) throw notFound(params.id!)
         return Response.json({ webhook, deliveries: await webhooks.deliveries(user.id, webhook.id) }, { headers: NO_STORE })
@@ -78,6 +89,7 @@ export function webhookRoutes(webhooks: RouteWebhooks, store?: Pick<Store, "audi
       path: `${PATH}/:id`,
       allow: ALLOW,
       async handle({ params, actor, user }) {
+        requireAppScope(actor)
         if (!(await webhooks.remove(user.id, params.id!, ownerOf(actor)))) throw notFound(params.id!)
         await store?.audit({ actor: user.id, action: "webhook.delete", target: params.id! })
         return new Response(null, { status: 204, headers: NO_STORE })

package/src/central/agent/webhooks.ts

@@ -2,10 +2,13 @@
 // app tokens register.
 //
 // - Registrations per user in the StateStore collection "webhooks" (key: the id `wh_<16 hex>`): url, events
-//   (exact types or `launch.*`), an optional label, `by` (`user`, or `app:<token id>` for an app token's own) and
-//   the signing secret `whsec_…`, returned only by register. Users see and manage all of theirs; an app token only
-//   its own. An app registration gets only events of what that app started (`by` of the event), and is dropped
-//   once its token is revoked or loses the scope (appAlive).
+//   (exact types or `<family>.*`; team.intake exact only), an optional label, `by` (`user`, or `app:<token id>` for
+//   an app token's own) and the signing secret `whsec_…`, returned only by register. Users see and manage all of
+//   theirs; an app token only its own. An app registration gets only events of what that app caused (`by` of the
+//   event: launches it started, intake it submitted; or a message party), and is dropped once its token is revoked
+//   or loses a required scope (appAlive, appScopes, webhookRequiredScopes).
+// - The sole source is the canonical journal (publishCanonical from AgentEvents' onAppend); team.intake arrives as
+//   the intake service's journal event (src/central/teams/intake.ts), IDs, enums, revisions and timestamps only.
 // - URLs: https on a public host (publicURLProblem), checked at registration and again, re-resolved, right before
 //   every send (publicFetch: no redirects, timeout, bounded response read). hub.json agents.webhooks.allowPrivate
 //   admits http and private targets (self-hosted receivers).
@@ -32,13 +35,17 @@ import { LAUNCH_STATES, type Launch } from "./launch-store"
 
 export const WEBHOOKS = "webhooks"
 export const WEBHOOK_OUTBOX = "webhook-outbox"
-/** Every event type a webhook can receive (phase 4: launch changes). */
+/** Every canonical event type a webhook can receive. */
 export const CANONICAL_WEBHOOK_EVENT_TYPES: readonly string[] = [
   "session.added", "session.removed", "session.changed", "session.archived", "session.named",
   "session.pinned",
   "blocker.opened", "blocker.closed", "machine.changed", "role.claimed", "role.released",
-  "message.changed", "launch.changed",
+  "message.changed", "launch.changed", "team.intake",
 ]
+/** Types no family wildcard selects (exact only): `team.*` would silently widen to team events webhooks do not send. */
+const EXACT_ONLY_TYPES: readonly string[] = ["team.intake"]
+/** The one type an app token may register for without events:subscribe (its scope is teams:submit). */
+const INTAKE_TYPE = "team.intake"
 /** A launch.changed event for a queued launch's new wait kind (not a state step). */
 export const isWaitChange = (event: Pick<AgentEvent, "type" | "data">): boolean => event.type === "launch.changed" && event.data.wait !== undefined
 
@@ -190,6 +197,7 @@ function eventsOf(raw: unknown): string[] {
     throw invalid(`events must be a list of 1 to ${MAX_WEBHOOK_EVENTS} event types`, `e.g. ["launch.*", "message.changed"]`)
   }
   for (const pattern of raw) {
+    if (pattern.endsWith(".*") && EXACT_ONLY_TYPES.some((type) => matches(pattern, type))) throw invalid(`${pattern} is not a webhook family`, `Use the exact type ${EXACT_ONLY_TYPES.join(", ")}`)
     if (!WEBHOOK_EVENT_TYPES.some((type) => matches(pattern, type))) throw invalid(`Unknown event type ${pattern}`, "Use a canonical event type or family wildcard")
   }
   return [...new Set(raw)]
@@ -199,7 +207,8 @@ export function webhookEventScopes(patterns: readonly string[]): string[] {
   const scopes = new Set<string>()
   if (patterns.some((pattern) => LAUNCH_STATES.some((state) => matches(pattern, `launch.${state}`)))) scopes.add("sessions:launch")
   for (const pattern of patterns) for (const type of CANONICAL_WEBHOOK_EVENT_TYPES) if (matches(pattern, type)) {
-    if (type === "message.changed") scopes.add("messages:read")
+    if (type === INTAKE_TYPE) scopes.add("teams:submit")
+    else if (type === "message.changed") scopes.add("messages:read")
     else if (type === "launch.changed") scopes.add("sessions:launch")
     else if (["session.archived", "session.named", "session.pinned", "role.claimed", "role.released"].includes(type)) scopes.add("sessions:manage")
     else scopes.add("sessions:read")
@@ -207,8 +216,17 @@ export function webhookEventScopes(patterns: readonly string[]): string[] {
   return [...scopes]
 }
 
+/**
+ * Every scope an app token needs for a registration's patterns: each family's scope, plus events:subscribe unless
+ * the patterns select only team.intake (an app with teams:submit gets its own submissions' changes by webhook).
+ */
+export function webhookRequiredScopes(patterns: readonly string[]): string[] {
+  const onlyIntake = patterns.length > 0 && patterns.every((pattern) => pattern === INTAKE_TYPE)
+  return [...(onlyIntake ? [] : ["events:subscribe"]), ...webhookEventScopes(patterns)]
+}
+
 export function canonicalWebhookEvent(source: string, userID: string, event: AgentEvent): WebhookEvent {
-  return { id: event.id, type: event.type, source, subject: event.subject.launchID ?? event.subject.messageID ?? event.subject.sessionID ?? event.subject.machineID ?? event.id, time: new Date(event.at).toISOString(), user: userID, schemaVersion: 1, data: { subject: event.subject, data: event.data } }
+  return { id: event.id, type: event.type, source, subject: event.subject.launchID ?? event.subject.messageID ?? event.subject.intakeID ?? event.subject.sessionID ?? event.subject.machineID ?? event.id, time: new Date(event.at).toISOString(), user: userID, schemaVersion: 1, data: { subject: event.subject, data: event.data } }
 }
 
 const view = ({ secret: _secret, ...rest }: Registration): WebhookView => rest
@@ -454,7 +472,7 @@ export class Webhooks {
       }
       if (registration.by !== "user" && this.deps.appScopes) {
         const scopes = this.deps.appScopes(userID, registration.by.slice("app:".length))
-        const required = ["events:subscribe", ...webhookEventScopes(registration.events)]
+        const required = webhookRequiredScopes(registration.events)
         if (!scopes || required.some((scope) => !scopes.includes(scope))) {
           await this.remove(userID, registration.id)
           return

package/src/central/artifacts/host.ts

@@ -242,7 +242,7 @@ export function artifactHost(deps: ArtifactHostDeps): { handle(request: Request,
 export interface ArtifactHostRouteDeps {
   readonly caps: ArtifactHostCaps
   /** Absent: this hub keeps no artifacts (422 unsupported). */
-  readonly artifacts?: Pick<ArtifactStore, "get" | "getRevision">
+  readonly artifacts?: Pick<ArtifactStore, "get" | "getRevision"> & Partial<Pick<ArtifactStore, "markViewed">>
 }
 
 const READ = { session: true, scope: "artifacts:read" } as const
@@ -297,6 +297,8 @@ export function artifactHostRoutes(deps: ArtifactHostRouteDeps): AgentRoute[] {
           ...(ttlMs !== undefined ? { ttlMs } : {}),
           ...(actor.kind === "user" ? { deviceID: actor.deviceID } : {}),
         })
+        // A preview's retention counts from its last view (session media §3).
+        if (artifact.origin === "preview") await artifacts.markViewed?.(user.id, artifact.id)
         const base = `${ARTIFACT_HOST_PATH}${token}/`
         const files = revision.blobs.map((b) => ({ ...(b.path !== undefined ? { path: b.path } : {}), mediaType: b.mediaType, bytes: b.bytes }))
         return Response.json({ capability, base, url: `${base}${entry}`, files }, { status: 201, headers: NO_STORE })

package/src/central/artifacts/maintenance.ts

@@ -1,6 +1,7 @@
 // Scheduled artifact upkeep (HWA-21 standalone; the cluster schedules it under a leader, HWA-22): for every user,
 // ArtifactStore.recover (finish crashed deletes and uploads, drop dangling references, collect unreferenced bytes
-// untouched for the grace period) and then purgeArchived (only when archive retention is configured). Runs never
+// untouched for the grace period) and then purgeArchived (preview retention always: archive previews not viewed for
+// 24 h, purge them 7 days later; other archived artifacts only when archive retention is configured). Runs never
 // overlap; a user's failure is logged (without user IDs or content) and the run goes on with the next user.
 import { realTimers } from "../backend/memory-bus"
 import type { Timers } from "../backend/types"