@huynle/hub 0.8.7 → 0.9.0

package/src/central/http.ts

@@ -8,7 +8,7 @@ import { diskAssets, type WebAssets } from "./assets"
 import path from "node:path"
 import { promisify } from "node:util"
 import { brotliCompress, constants as zlib, gzip } from "node:zlib"
-import { formAnswerProblem, NOT_A_USER_MESSAGE, RECORDING_AUDIO_RESULT_HEADER, REVERT_BUSY, REVERT_END_BUSY, PROMPT_IMAGE_MIMES, WORKSPACE_LIMITS, promptImagesProblem, redactEmbeddedMedia, type AvailableModel, type CoreOp, type EnrollStart, type FormAnswer, type ModelSelection, type PermissionDecision, type PromptImage } from "../protocol"
+import { formAnswerProblem, isPreviewPath, parseMediaAllowlist, parseMediaRef, PREVIEW_BUNDLE_LIMITS, NOT_A_USER_MESSAGE, RECORDING_AUDIO_RESULT_HEADER, REVERT_BUSY, REVERT_END_BUSY, PROMPT_IMAGE_MIMES, WORKSPACE_LIMITS, promptImagesProblem, redactEmbeddedMedia, type AvailableModel, type CoreOp, type EnrollStart, type FormAnswer, type ModelSelection, type PermissionDecision, type PromptImage, type ResultFor } from "../protocol"
 import { isLoopbackAddress, isLoopbackHost, isLoopbackURL, loopbackOrigins } from "../loopback"
 import { speakable } from "../speakable"
 import { Auth, RateLimitError, ValidationError } from "./auth"
@@ -16,12 +16,17 @@ import { emailAllowed, type CentralConfig } from "./config"
 import { authPage, cookieValue, deviceName, OIDC_COOKIE, OidcClient, OidcError } from "./oidc"
 import { isNotificationKind, Push, type PushSender } from "./push"
 import { pushEndpointProblem, resolveHost as systemResolveHost, type ResolveHost } from "./push-target"
+import { createFetcher, parseDenyCidrs, type Fetcher } from "./fetcher"
+import { createRemoteMedia } from "./media-remote"
+import { createUnfurl } from "./media-unfurl"
+import { createFetchBudget } from "./fetch-budget"
+import { createTimelineMedia } from "./media-timeline"
 import { Webhooks } from "./agent/webhooks"
 import { issueAppToken } from "./agent/app-tokens"
 import { AGENT_EVENTS_AGE_MS, AGENT_EVENTS_MAX, AgentEvents, archiveEvent, conciergeEvent, type AgentEvent } from "./agent/events"
 import { EventWriters } from "./agent/event-writers"
 import { MemoryEventLog } from "./backend/memory-events"
-import { WEBHOOK_SCOPE } from "./agent/webhook-routes"
+import { WEBHOOK_APP_SCOPES } from "./agent/webhook-routes"
 import { hubBackends, type Backends } from "./backend"
 import { createResolver, type AgentActor, type BearerVerifier, type CredentialMode } from "./agent/actor"
 import { ActingSwitch } from "./agent/acting-switch"
@@ -45,7 +50,7 @@ import { SessionTokens } from "./agent/session-tokens"
 import { SessionTokenPush } from "./session-token-push"
 import { TokenKeys } from "./token-keys"
 import { EventLog } from "./events-log"
-import { BusyError, Registry } from "./registry"
+import { BusyError, Registry, type Timers } from "./registry"
 import { createActions, type Unsupported, unsupportedMessage } from "./actions"
 import { IntentRetention, SessionIntents, withPromptIntents } from "./agent/intents"
 import { audioFormat, SpeechError } from "./speech/provider"
@@ -78,6 +83,8 @@ import { recordingRoutes } from "./recording/routes"
 import { wrapConciergeSend } from "./recording/concierge-taps"
 import { ARTIFACT_UPLOAD_LIMITS } from "./artifacts/routes"
 import { ArtifactStore } from "./artifacts/store"
+import { messageTexts, pickHtmlBlock, PREVIEW_LIMITS } from "./artifacts/previews"
+import { BundleProtocolError, fetchPreviewBundle } from "./artifacts/preview-bundle"
 import { artifactHost, isArtifactHostPath } from "./artifacts/host"
 import { CONSOLE_CSP, cspHeader } from "./csp"
 import { ArtifactHostCaps } from "./artifacts/host-caps"
@@ -120,6 +127,10 @@ export interface Speech {
 
 export interface CentralOptions {
   readonly config: CentralConfig
+  /** HTML preview retention (default: archived 24 h after the last view, purged 7 days later). */
+  readonly previewRetention?: { readonly archiveAfterMs?: number; readonly purgeAfterMs?: number }
+  /** The registry's timers (tests: a fake clock for its delayed checks); real timers by default. */
+  readonly registryTimers?: Timers
   /** The built web app (web/dist, see web/vite.config.ts) on disk; or pass `web` (e.g. files embedded in a compiled binary). */
   readonly webDir?: string
   readonly web?: WebAssets
@@ -134,6 +145,8 @@ export interface CentralOptions {
   readonly pushSender?: PushSender
   /** Resolves push endpoint and webhook hosts (SSRF checks); the system resolver by default. */
   readonly resolveHost?: ResolveHost
+  /** The outbound fetcher of /api/media/remote and /api/media/unfurl (tests); default: resolveHost, the built-in deny list and HUB_FETCH_DENY_CIDRS. */
+  readonly remoteFetcher?: Fetcher
   /** Clock for sign-in expiry, the store, the registry and the backends (tests). */
   readonly now?: () => number
   /** Shared state for new code (default: in memory, see ./backend). */
@@ -146,6 +159,8 @@ export interface CentralOptions {
     readonly turnGraceMs?: number
     /** `Prefer: respond-async` turns: how long the hub waits for a quick result before answering 202. */
     readonly turnAcceptMs?: number
+    /** (S4 M3) The longest one timeline image may take from the spoke, all chunks together (default 60 s). */
+    readonly mediaDeadlineMs?: number
     readonly heartbeatMs?: number
     readonly staleMs?: number
     /** Per node op request timeouts (see NODE_TIMEOUTS_MS). */
@@ -162,6 +177,9 @@ export interface CentralOptions {
     /** drain(): how long it waits for requests in flight, and the bye's retryAfterMs (see DRAIN_TIMEOUT_MS, DRAIN_RETRY_AFTER_MS). */
     readonly drainTimeoutMs?: number
     readonly drainRetryAfterMs?: number
+    /** Launches: the end watcher's settle and the engine's tick (see END_SETTLE_MS, END_TICK_MS; test fixtures). */
+    readonly launchSettleMs?: number
+    readonly launchTickMs?: number
   }
 }
 
@@ -288,6 +306,13 @@ interface Route extends RouteInfo {
 
 const NO_STORE = { "cache-control": "no-store" }
 
+/** Who asks for a timeline image, and how (If-None-Match, ?download=1). */
+interface MediaCaller {
+  readonly request: Request
+  readonly url: URL
+  readonly userID: string
+}
+
 export const COOKIE = "voice_device"
 const COOKIE_MAX_AGE = 400 * 24 * 60 * 60
 const SSE_HEARTBEAT_MS = 20_000
@@ -309,6 +334,8 @@ export const TURN_ACCEPT_MS = 1500
 const NO_OWNER = "No OpenCode process for this session is connected"
 /** A message ID in a fork or revert request (as the spoke protocol bounds it). */
 const MESSAGE_ID = /^[A-Za-z0-9_.:@/+~-]{1,300}$/
+/** A message ID in a media URL: the same characters without `/`, and never `..` (it names a message, never a path). */
+const MEDIA_MESSAGE_ID = /^(?!.*\.\.)[A-Za-z0-9_.:@+~-]{1,300}$/
 const AUTO_NAME_OUTDATED = "Update the Hub plugin to use Auto-name"
 const NOT_EXPOSED = "Voice is not enabled for this session"
 /** A permission or question that is not pending any more: someone answered it elsewhere, or it expired. */
@@ -411,7 +438,7 @@ export function startCentral(options: CentralOptions): Central {
     ? Store.shared({ state: backends.state, bus: backends.bus, now, instanceID: `${config.cluster.podID}-${randomUUID().slice(0, 8)}` })
     : Store.open(config.stateDir, now, { mode: config.auth.mode })
   // A machine's tenant is its owner (read live: ownership moves on migration).
-  const registry = new Registry(now, undefined, (machineID) => store.machines().find((m) => m.id === machineID)?.ownerID)
+  const registry = new Registry(now, options.registryTimers, (machineID) => store.machines().find((m) => m.id === machineID)?.ownerID)
   const nodes = new NodeRegistry((machineID) => store.machines().find((m) => m.id === machineID)?.ownerID, now)
   const push = new Push({ store, subject: config.vapidSubject, sender: options.pushSender, kv: backends.kv })
   // CON-04: the Concierge's state record is read early (the Concierge-only authority, hiding, the inbound rule and
@@ -558,6 +585,7 @@ export function startCentral(options: CentralOptions): Central {
   // options.fetch is for speech providers only; sign-in always talks to the real issuer.
   const oidc = config.auth.mode === "oidc" ? new OidcClient({ config: config.auth, publicURL, now, kv: backends.kv, counters: backends.counters }) : undefined
   /** Speech settings scope of a user: "local" (pairing mode) uses the server default directly. */
+  const mediaSettingsView = (userID: string) => ({ allowlist: store.mediaAllowlist(userID), remoteFetch: config.remoteFetch !== false })
   const speechScope = (userID: string) => (userID === LOCAL_USER ? undefined : userID)
   const speechFor = (userID: string): Speech => options.speech ?? speechSettings.forUser(speechScope(userID))
   const tokenKeys = TokenKeys.open(config.stateDir)
@@ -631,6 +659,12 @@ export function startCentral(options: CentralOptions): Central {
   // Cluster mode: a catalog change stays on this pod (each pod's registry emits its own for remote slices); the rest
   // goes to the tenant's streams on every pod.
   registry.subscribe((message, tenant) => (live && message.type === "catalog" ? catalogHere() : broadcast({ ...message }, tenant !== undefined ? { tenant } : {})))
+  // (voice front P1) A front that failed is recorded with the session's recordings (the fallback is visible there).
+  registry.subscribe((message, tenant) => {
+    if (message.type === "conversation" && message.reason === "front_failed" && tenant !== undefined) {
+      recordings?.hub(tenant, message.sessionID, "conversation", { on: true, front: false, reason: "front_failed" })
+    }
+  })
   registry.subscribeAlerts((alert) => {
     // Push goes to the session owner's devices only; an alert without an owner goes nowhere.
     if (!alert.owner) return
@@ -892,6 +926,24 @@ export function startCentral(options: CentralOptions): Central {
     }
   })
   registry.onHumanTurn((sessionID) => void humanTurn(sessionID))
+  // (S4 M3) Timeline images, cached per user on this pod; a deleted session or a committed revert forgets them.
+  const timelineMedia = createTimelineMedia({
+    request: (connID, req) => spokes.request(connID, req),
+    now,
+    ...(options.timing?.mediaDeadlineMs !== undefined ? { deadlineMs: options.timing.mediaDeadlineMs } : {}),
+  })
+  const mediaRevertCommits = new Map<string, number>()
+  registry.onSessions((connID) => {
+    for (const { sessionID, committed } of registry.revertCommits(connID)) {
+      if (mediaRevertCommits.get(sessionID) === committed.at) continue
+      mediaRevertCommits.set(sessionID, committed.at)
+      timelineMedia.forgetSession(sessionID)
+    }
+  })
+  registry.onSessionDeleted((sessionID) => {
+    mediaRevertCommits.delete(sessionID)
+    timelineMedia.forgetSession(sessionID)
+  })
   // (CON-02) Session intents; the journal is created below (appends happen only once requests arrive).
   const intents = new SessionIntents({
     state: backends.state,
@@ -951,6 +1003,8 @@ export function startCentral(options: CentralOptions): Central {
       if (isConciergeLaunch(launch)) conciergeSupervisor.kick(launch.owner)
     },
     intents,
+    ...(options.timing?.launchSettleMs !== undefined ? { settleMs: options.timing.launchSettleMs } : {}),
+    ...(options.timing?.launchTickMs !== undefined ? { tickMs: options.timing.launchTickMs } : {}),
     // FX-02: a launch of a revoked app token (`app:<16 hex>` no longer among the user's tokens) is flagged, not stopped.
     launchers: { revoked: (userID, by) => /^app:[0-9a-f]{16}$/.test(by) && !(store.user(userID)?.agent?.appTokens ?? []).some((t) => `app:${t.id}` === by) },
     profiles: { applyAtLaunch: async (userID, sessionID, ref) => (profileApplier ? profileApplier.applyAtLaunch(userID, sessionID, ref) : [`profile ${ref.profileID} v${ref.version} not applied: the hub is starting`]) },
@@ -1007,7 +1061,7 @@ export function startCentral(options: CentralOptions): Central {
     users: () => store.users().map((u) => u.id),
     resolve: options.resolveHost ?? systemResolveHost,
     ...(config.webhooksAllowPrivate ? { allowPrivate: true } : {}),
-    appAlive: (userID, tokenID) => store.agentData(userID).appTokens?.some((t) => t.id === tokenID && Array.isArray(t.scopes) && t.scopes.includes(WEBHOOK_SCOPE)) === true,
+    appAlive: (userID, tokenID) => store.agentData(userID).appTokens?.some((t) => t.id === tokenID && Array.isArray(t.scopes) && WEBHOOK_APP_SCOPES.some((scope) => t.scopes!.includes(scope))) === true,
     appScopes: (userID, tokenID) => store.agentData(userID).appTokens?.find((t) => t.id === tokenID)?.scopes,
     userAgent: `hub/${options.version ?? "0.0.0"}`,
   })
@@ -1052,6 +1106,8 @@ export function startCentral(options: CentralOptions): Central {
         blobs: backends.blobs,
         now,
         workspaces: artifactWorkspacesFromState(backends.state),
+        ...(options.previewRetention?.archiveAfterMs !== undefined ? { previewArchiveAfterMs: options.previewRetention.archiveAfterMs } : {}),
+        ...(options.previewRetention?.purgeAfterMs !== undefined ? { previewPurgeAfterMs: options.previewRetention.purgeAfterMs } : {}),
         onEvent: (userID, event) => void agentEvents.append(userID, artifactJournalEvent(event)).catch((cause) => console.error(`[hub] artifact event failed: ${(cause as Error).message}`)),
       })
     : undefined
@@ -1183,8 +1239,30 @@ export function startCentral(options: CentralOptions): Central {
   const teamStaffing = new TeamStaffingService({ state: backends.state, teams: teamStore, seats: teamSeats, workspaces: workspaceStore, members: workspaceMembers, supervision: workspaceSupervision, presence: teamPresence, sessionDirectory, launches, grants, acting, audit, profiles, events: agentEvents, now, protects: conciergeProtects(conciergeTimedIdentity) })
   registry.onSessionDeleted((sessionID, tenant) => void teamStaffing.sessionEnded(tenant, sessionID).catch((cause) => console.error(`[hub] team session end failed: ${(cause as Error).message}`)))
   launchFeed.subscribe((userID, launch) => void teamStaffing.launchChanged(userID, launch).catch((cause) => console.error(`[hub] team staffing launch failed: ${(cause as Error).message}`)), { origin: true })
-  // Team intake (HWA-36): delivered to an entry seat from the fixed party app:team-intake (never the submitter).
-  teamIntake = new TeamIntakeService({ state: backends.state, teams: teamStore, seats: teamSeats, staffing: teamStaffing, members: workspaceMembers, presence: teamPresence, events: agentEvents, now, deliver: async (userID, sessionID, text, options = {}) => ({ messageID: (await delivery.send(userID, intakeActor(userID), sessionID, "msg", text, options.hop === undefined ? {} : { chainHop: options.hop })).message.id }), hopOf: (userID, sessionID) => delivery.hops.next(userID, { kind: "session", sessionID }) })
+  // Team intake (HWA-36): delivered to an entry seat from the fixed party app:team-intake (never the submitter). The
+  // message inherits the item's notAfter (H4); queued items past it are cancelled by the team-intake leader's sweep.
+  teamIntake = new TeamIntakeService({
+    state: backends.state,
+    teams: teamStore,
+    seats: teamSeats,
+    staffing: teamStaffing,
+    members: workspaceMembers,
+    presence: teamPresence,
+    events: agentEvents,
+    now,
+    users: allUsers,
+    deliver: async (userID, sessionID, text, options = {}) => ({
+      messageID: (
+        await delivery.send(userID, intakeActor(userID), sessionID, "msg", text, {
+          ...(options.hop === undefined ? {} : { chainHop: options.hop }),
+          ...(options.notAfter === undefined ? {} : { notAfter: options.notAfter }),
+        })
+      ).message.id,
+    }),
+    hopOf: (userID, sessionID) => delivery.hops.next(userID, { kind: "session", sessionID }),
+  })
+  const intakeService = teamIntake
+  void leader("team-intake", { onElected: () => intakeService.start(), onDeposed: () => intakeService.stop() }).start() // created after the other leaders were started
   // Supervisor checkpoints and batched digests (HWA-11): acknowledgments flush before answering; digests reach
   // supervisor sessions through Delivery (as coordinatorActor) from the workspace-coordinator leader.
   const workspaceCursors = journalCursors(tokenKeys, agentEvents)
@@ -1432,7 +1510,7 @@ export function startCentral(options: CentralOptions): Central {
     onDeposed: () => (conciergeSupervisor.stop(), conciergeParts.notifier.stop()),
   })
   void conciergeLeader.start()
-  const agentDeps = { recording: { call: (userID: string, sessionID: string, fields: Parameters<RecordingService["conciergeCall"]>[2]) => recordingService.conciergeCall(userID, sessionID, fields) }, intents, teamDiscovery, draining: drainSignal.signal, store, sessionTokens, directory, registry, spokes, delivery, decisions, feed, heartbeatMs, now, audit, grants, grantRequests, acting, actions, escalate, launches, webhooks, agentEvents, eventCursorKeys: tokenKeys, maxPromptChars: MAX_PROMPT_CHARS, profiles, workspaces, workspaceCheckpoints, teamIntake, graph: { teams: { teams: teamStore, seats: teamSeats! } }, teams: { teams: teamStore, seats: teamSeats!, staffing: teamStaffing }, artifacts: { ...(artifacts && backends.blobs ? { artifacts, blobs: backends.blobs } : {}), state: backends.state, now }, artifactHost: { caps: artifactHostCaps, ...(artifacts ? { artifacts } : {}) }, concierge: { state: backends.state, activity: conciergeActivity, results: conciergeResults, identity: conciergeTimedIdentity, protects: conciergeProtects(conciergeTimedIdentity), service: conciergeService, models: machineModels({ serviceFor: (machineID) => registry.serviceFor(machineID), reportedSessions: (connID) => registry.reportedSessions(connID), request: (connID, req) => spokes.request(connID, req) }), routes: () => conciergeParts.tiers.routes(), armed: conciergeArmed, timeZone: conciergeBoardDeps.timeZone, coverage: conciergeCoverage } }
+  const agentDeps = { recording: { call: (userID: string, sessionID: string, fields: Parameters<RecordingService["conciergeCall"]>[2]) => recordingService.conciergeCall(userID, sessionID, fields) }, intents, teamDiscovery, draining: drainSignal.signal, store, sessionTokens, directory, registry, spokes, delivery, decisions, messageState: backends.state, feed, heartbeatMs, now, audit, grants, grantRequests, acting, actions, escalate, launches, webhooks, agentEvents, eventCursorKeys: tokenKeys, maxPromptChars: MAX_PROMPT_CHARS, profiles, workspaces, workspaceCheckpoints, teamIntake, graph: { teams: { teams: teamStore, seats: teamSeats! } }, teams: { teams: teamStore, seats: teamSeats!, staffing: teamStaffing }, artifacts: { ...(artifacts && backends.blobs ? { artifacts, blobs: backends.blobs } : {}), state: backends.state, now }, artifactHost: { caps: artifactHostCaps, ...(artifacts ? { artifacts } : {}) }, concierge: { state: backends.state, activity: conciergeActivity, results: conciergeResults, identity: conciergeTimedIdentity, protects: conciergeProtects(conciergeTimedIdentity), service: conciergeService, models: machineModels({ serviceFor: (machineID) => registry.serviceFor(machineID), reportedSessions: (connID) => registry.reportedSessions(connID), request: (connID, req) => spokes.request(connID, req) }), routes: () => conciergeParts.tiers.routes(), armed: conciergeArmed, timeZone: conciergeBoardDeps.timeZone, coverage: conciergeCoverage } }
   const resolveActor = createResolver({
     cookieName: COOKIE,
     findDevice: (token) => deviceOfToken(token),
@@ -1586,10 +1664,16 @@ export function startCentral(options: CentralOptions): Central {
     store.machines().find((m) => m.id === machineID && !m.revoked && m.ownerID === userID)
 
   /** Session routes that also answer for the user's offline sessions the directory knows (hub-side data only). */
-  const OFFLINE_SESSION_ROUTES = new Set(["/api/sessions/:session/messages"])
+  const OFFLINE_SESSION_ROUTES = new Set(["/api/sessions/:session/messages", "/api/sessions/:session/previews"])
   /** No spoke reports the session (for anyone) and the user's directory has a record of it (not deleted). */
   const knownOffline = (userID: string, sessionID: string) =>
     registry.sessionTenant(sessionID) === undefined && (store.agentData(userID).sessions ?? []).some((s) => s.sessionID === sessionID && s.deletedAt === undefined)
+  // (RF1, RF3) Web images and link previews for the console through the safe fetcher (design §4): signed-in users
+  // only, one fetcher and ONE per-user budget (30 a minute, 4 at once) for both routes together.
+  const remoteFetcher = options.remoteFetcher ?? createFetcher({ resolve: options.resolveHost ?? systemResolveHost, denyCidrs: parseDenyCidrs((config.fetchDenyCidrs ?? []).join(",")) })
+  const fetchBudget = createFetchBudget({ now })
+  const remoteMedia = createRemoteMedia({ fetcher: remoteFetcher, enabled: config.remoteFetch !== false, now, audit: (entry) => store.audit(entry), budget: fetchBudget })
+  const unfurl = createUnfurl({ fetcher: remoteFetcher, enabled: config.remoteFetch !== false, now, audit: (entry) => store.audit(entry), budget: fetchBudget })
   const route = (method: string, path: string, access: Access, handle: Handler, exposed = false): Route => {
     const keys: string[] = []
     const pattern = new RegExp(`^${path.replace(/:([a-z]+)/g, (_, key: string) => (keys.push(key), "([^/]+)"))}$`)
@@ -1628,6 +1712,8 @@ export function startCentral(options: CentralOptions): Central {
       }),
     ),
     route("GET", "/api/machines", "user", ({ user }) => Response.json({ machines: machines(user.id) })),
+    route("GET", "/api/media/remote", "user", ({ user, request, url }) => remoteMedia.handle(user.id, request, url)),
+    route("GET", "/api/media/unfurl", "user", ({ user, request, url }) => unfurl.handle(user.id, request, url)),
     route("GET", "/api/events", "user", ({ request, server, user, device, url }) => {
       const shown = streamSessionsQuery(url)
       if ("problem" in shown) return error(400, shown.problem)
@@ -1771,6 +1857,12 @@ export function startCentral(options: CentralOptions): Central {
       conciergeTouch(user.id)
       return Response.json(view, { headers: NO_STORE })
     }),
+    // (RF2) The user's media allowlist (Settings → Media) and whether this hub fetches web images at all.
+    route("GET", "/api/settings/media", "user", ({ user }) => Response.json(mediaSettingsView(user.id), { headers: NO_STORE })),
+    route("PUT", "/api/settings/media", "user", async ({ request, user }) => {
+      await store.setMediaAllowlist(user.id, mediaSettingsInput(await jsonBody(request)))
+      return Response.json(mediaSettingsView(user.id), { headers: NO_STORE })
+    }),
     route("GET", "/api/settings/speech/models", "user", async ({ url, user }) => {
       const kind = url.searchParams.get("kind")
       if (kind !== "stt" && kind !== "tts") return error(400, "Expected kind=stt or kind=tts")
@@ -1803,7 +1895,11 @@ export function startCentral(options: CentralOptions): Central {
       "/api/sessions/:session/interrupt",
       "session",
       async ({ params }) => {
-        await spokes.request(ownerOf(params.session!, "interrupt"), { op: "interrupt", sessionID: params.session! })
+        // (voice front P1) While a front is active, an interrupt stops the front (barge-in), not the session's work.
+        const front = registry.frontRoute(params.session!)
+        // A front that cannot be reached failed: the session talks directly (front_failed), never a 502.
+        const viaFront = front ? await spokes.request(front.connID, { op: "interrupt", sessionID: front.sessionID }).then(() => true, () => (registry.frontLost(params.session!), false)) : false
+        if (!viaFront) await spokes.request(ownerOf(params.session!, "interrupt"), { op: "interrupt", sessionID: params.session! })
         registry.cancelTurns(params.session!)
         recordingTap(params.session!, "interrupt", {})
         return new Response(null, { status: 204 })
@@ -1900,7 +1996,12 @@ export function startCentral(options: CentralOptions): Central {
     // harnesses) never ships image bytes to the console in a tool detail.
     route("GET", "/api/sessions/:session/timeline/messages/:message/parts/:part", "session", async ({ params }) =>
       Response.json(redactEmbeddedMedia(await spokes.request(ownerOf(params.session!), { op: "timelinePart", sessionID: params.session!, messageID: params.message!, partID: params.part! })), { headers: NO_STORE })),
-    route("GET", "/api/sessions/:session/timeline/messages/:message/files/:index", "session", ({ params }) => timelineFile(params.session!, params.message!, params.index!)),
+    route("GET", "/api/sessions/:session/timeline/messages/:message/files/:index", "session", ({ params, request, url, user }) => timelineFile(params.session!, params.message!, params.index!, { request, url, userID: user.id })),
+    // (S4 M3) A timeline image by ref, pulled from the spoke in chunks (./media-timeline.ts; files/:index is an alias).
+    route("GET", "/api/sessions/:session/timeline/messages/:message/media/:ref", "session", ({ params, request, url, user }) =>
+      timelineMediaRoute({ request, url, userID: user.id }, params.session!, params.message!, params.ref!)),
+    // (session media §3) An HTML preview of the message's n-th ```html block, read from the spoke, never the console.
+    route("POST", "/api/sessions/:session/previews", "session", ({ params, request, user }) => createPreview(user.id, params.session!, request)),
     route(
       "GET",
       "/api/sessions/:session/context",
@@ -2179,11 +2280,102 @@ export function startCentral(options: CentralOptions): Central {
     return Response.json({ mode: "turn" }, { status: 202, headers: { "preference-applied": "respond-async" } })
   }
 
-  /** GET …/timeline/messages/:message/files/:index: one image of a user message, as bytes. */
-  async function timelineFile(sessionID: string, messageID: string, rawIndex: string): Promise<Response> {
+  /**
+   * POST /api/sessions/:session/previews {messageID, block}: the message's `block`-th (0-based) ```html block, from
+   * the spoke's timeline (newest-first pages), stored as a private preview artifact (ArtifactStore.savePreview: the
+   * same content reuses its revision). Answers {artifact, revision, reused, host}: POST `host` (the artifact host
+   * mint route) opens it. 404 no such message or block (code too_old: older than the newest PREVIEW_LIMITS.pages
+   * timeline pages), 409 spoke offline, 413 over PREVIEW_LIMITS.htmlBytes.
+   * {messageID, path} (session media §3 4b): the local HTML page the message names and its files, through the spoke's
+   * previewBundle op (createPagePreview).
+   */
+  async function createPreview(userID: string, sessionID: string, request: Request): Promise<Response> {
+    const input = await body(request)
+    const extra = Object.keys(input).find((k) => k !== "messageID" && k !== "block" && k !== "path")
+    if (extra !== undefined) return error(400, `Unknown field ${JSON.stringify(extra.slice(0, 50))}`)
+    const { messageID, block, path } = input
+    if (typeof messageID !== "string" || !/^[A-Za-z0-9_.:-]{1,200}$/.test(messageID)) return error(400, "messageID must be a message ID")
+    if (path !== undefined) {
+      if (block !== undefined) return error(400, "Send either block or path, not both")
+      if (!isPreviewPath(path)) return error(400, `path must be 1–${PREVIEW_BUNDLE_LIMITS.pathMax} characters on one line`)
+      return createPagePreview(userID, sessionID, messageID, path)
+    }
+    if (typeof block !== "number" || !Number.isSafeInteger(block) || block < 0 || block > 9999) return error(400, "block must be a whole number 0–9999")
+    if (!artifacts) return error(422, "This hub does not store artifacts", "unsupported")
+    const connID = ownerOf(sessionID)
+    const texts = await messageTexts((page) => spokes.request(connID, { op: "timeline", sessionID, order: "desc", ...page }), messageID)
+    if ("error" in texts) {
+      return texts.error === "too_old" ? error(404, "This message is too old to preview", "too_old") : error(404, "No such message", "not_found")
+    }
+    const picked = pickHtmlBlock(texts.texts, block)
+    if ("error" in picked) {
+      return picked.error === "not_found" ? error(404, "No HTML block at that index", "not_found") : error(413, `The HTML block is larger than ${PREVIEW_LIMITS.htmlBytes} bytes`, "too_large")
+    }
+    try {
+      const saved = await artifacts.savePreview(userID, { sessionID, messageID, block }, picked.html)
+      const host = `/api/agent/artifacts/${saved.artifact.id}/revisions/${saved.revision.id}/host`
+      return Response.json({ ...saved, host }, { status: saved.reused ? 200 : 201, headers: NO_STORE })
+    } catch (cause) {
+      return decisionFailure(cause)
+    }
+  }
+
+  /**
+   * POST …/previews {messageID, path}: the page `path` names (as written in the message) and the files it refers to,
+   * read by the owning spoke under its media path policy (op previewBundle, feature "previewBundle"; the hub reads the
+   * files the manifest does not inline chunk by chunk and checks each against it), stored as a preview artifact
+   * revision (savePreview: unchanged files reuse it, a changed file is a new revision). Answers as for a block plus
+   * `skipped` (files left out, with reasons) and `skippedMore`. 404 refused (not a page of this message under the
+   * policy) or not_found (no such message, or hidden by a revert), 409 spoke offline or the page kept changing
+   * (changed), 413 the page is over PREVIEW_BUNDLE_LIMITS.fileBytes ({bytes, max}), 422 a spoke without the feature
+   * ({feature, harness}) or a hub without artifacts, 502 a malformed bundle.
+   */
+  async function createPagePreview(userID: string, sessionID: string, messageID: string, path: string): Promise<Response> {
+    if (!artifacts) return error(422, "This hub does not store artifacts", "unsupported")
+    const connID = ownerOf(sessionID)
+    if (!registry.supports(connID, "previewBundle")) {
+      const lacking = { feature: "previewBundle", harness: registry.harnessOf(connID) ?? "unknown" }
+      return Response.json({ error: unsupportedMessage(lacking), code: "unsupported", ...lacking }, { status: 422, headers: NO_STORE })
+    }
+    let fetched
+    try {
+      fetched = await fetchPreviewBundle((chunk) => spokes.request(connID, { op: "previewBundle", sessionID, messageID, path, ...chunk }))
+    } catch (cause) {
+      if (cause instanceof BundleProtocolError) return error(502, cause.message, "bad_bundle")
+      throw cause
+    }
+    if ("error" in fetched) {
+      switch (fetched.error) {
+        case "refused":
+          return error(404, "This page isn't one of this session's files", "refused")
+        case "too_large":
+          return Response.json({ error: `The page is larger than ${fetched.max} bytes`, code: "too_large", bytes: fetched.bytes, max: fetched.max }, { status: 413, headers: NO_STORE })
+        case "changed":
+          return error(409, "The page kept changing while it was read; try again", "changed")
+        default:
+          return error(404, "No such message", "not_found")
+      }
+    }
+    try {
+      const saved = await artifacts.savePreview(userID, { sessionID, messageID, path }, fetched.bundle)
+      const host = `/api/agent/artifacts/${saved.artifact.id}/revisions/${saved.revision.id}/host`
+      const skipped = { skipped: fetched.skipped, ...(fetched.skippedMore ? { skippedMore: fetched.skippedMore } : {}) }
+      return Response.json({ ...saved, host, ...skipped }, { status: saved.reused ? 200 : 201, headers: NO_STORE })
+    } catch (cause) {
+      return decisionFailure(cause)
+    }
+  }
+
+  /**
+   * GET …/timeline/messages/:message/files/:index: one image of a user message, as bytes. On a spoke with
+   * "timelineMedia" it is media/f<index> (chunked, verified, cached); else the older single-answer timelineFile op.
+   */
+  async function timelineFile(sessionID: string, messageID: string, rawIndex: string, caller: MediaCaller): Promise<Response> {
     const index = /^\d{1,3}$/.test(rawIndex) ? Number(rawIndex) : NaN
     if (!Number.isInteger(index) || messageID.length > 300) return error(400, "Expected an attachment index 0–999")
-    const { file, tooLarge } = await spokes.request(ownerOf(sessionID), { op: "timelineFile", sessionID, messageID, index })
+    const connID = ownerOf(sessionID)
+    if (registry.supports(connID, "timelineMedia")) return timelineMediaRoute(caller, sessionID, messageID, `f${index}`)
+    const { file, tooLarge } = await spokes.request(connID, { op: "timelineFile", sessionID, messageID, index })
     if (tooLarge) return error(413, "This image is too large to show here")
     // Only image types that are safe to render inline are served (never SVG or HTML).
     if (!file || typeof file.data !== "string" || !PROMPT_IMAGE_MIMES.includes(file.mime)) return error(404, "No such image")
@@ -2193,6 +2385,33 @@ export function startCentral(options: CentralOptions): Central {
     })
   }
 
+  /**
+   * GET …/timeline/messages/:message/media/:ref (S4 M3): 400 for a malformed ref or message ID, 409 offline, 422
+   * unsupported {feature, harness} when the owning spoke did not announce timelineMedia; else ./media-timeline.ts.
+   */
+  async function timelineMediaRoute(caller: MediaCaller, sessionID: string, messageID: string, ref: string): Promise<Response> {
+    const parsed = parseMediaRef(ref)
+    if (!parsed) return error(400, "Expected a media ref (f<n>, t<part>.<item> or p:<path>)")
+    if (!MEDIA_MESSAGE_ID.test(messageID)) return error(400, "Expected a message ID")
+    const connID = ownerOf(sessionID)
+    if (!registry.supports(connID, "timelineMedia")) {
+      const lacking = { feature: "timelineMedia", harness: registry.harnessOf(connID) ?? "unknown" }
+      return Response.json({ error: unsupportedMessage(lacking), code: "unsupported", ...lacking }, { status: 422, headers: NO_STORE })
+    }
+    return timelineMedia.serve({
+      userID: caller.userID,
+      connID,
+      sessionID,
+      messageID,
+      ref,
+      parsed,
+      ifNoneMatch: caller.request.headers.get("if-none-match"),
+      download: caller.url.searchParams.get("download") === "1",
+      bypassCache: registry.revertStaged(sessionID),
+      revertAt: registry.revertCommits(connID).find((c) => c.sessionID === sessionID)?.committed.at,
+    })
+  }
+
   /**
    * Every selection must be in the session's catalog (provider, model and variant), so a typo cannot leave
    * the session failing every turn. A catalog that cannot be fetched is a 502, never an accepted selection.
@@ -2300,9 +2519,21 @@ export function startCentral(options: CentralOptions): Central {
     const text = typeof raw === "string" ? raw.trim() : ""
     if (!text) return error(400, "Empty utterance")
     if (text.length > MAX_UTTERANCE_CHARS) return error(400, `Utterance longer than ${MAX_UTTERANCE_CHARS} characters`)
-    const connID = ownerOf(sessionID, "steer")
+    // (voice front P1) While a front is active, utterances go to the front; it relays them to the session.
+    const front = registry.frontRoute(sessionID)
     await humanTurn(sessionID)
-    const { inboxID } = await spokes.request(connID, { op: "steer", sessionID, text })
+    // A front that cannot take it failed: the session talks directly (front_failed), never a 502.
+    let inboxID = front
+      ? await spokes.request(front.connID, { op: "steer", sessionID: front.sessionID, text }).then(
+          (result) => result.inboxID,
+          (cause) => {
+            console.warn(`[hub] voice front of ${sessionID} did not take the utterance: ${(cause as Error).message}`)
+            registry.frontLost(sessionID)
+            return undefined
+          },
+        )
+      : undefined
+    if (inboxID === undefined) inboxID = (await spokes.request(ownerOf(sessionID, "steer"), { op: "steer", sessionID, text })).inboxID
     recordingTap(sessionID, "utterance.received", { inboxID, text })
     registry.trackUtterance(sessionID, inboxID)
     return Response.json({ inboxID }, { status: 202 })
@@ -2357,18 +2588,32 @@ export function startCentral(options: CentralOptions): Central {
   }
 
   async function conversation(request: Request, sessionID: string): Promise<Response> {
-    const on = (await body(request)).on
-    if (typeof on !== "boolean") return error(400, "Expected {on: boolean}")
+    const input = await body(request)
+    const on = input.on
+    if (typeof on !== "boolean" || (input.front !== undefined && typeof input.front !== "boolean")) return error(400, "Expected {on: boolean, front?: boolean}")
+    // (voice front P1) `front`: put a hidden voice front in front of the session, when its spoke serves it.
+    const wantsFront = on && input.front === true
+    const hadFront = registry.wantsFront(sessionID)
     // Turning off always clears the hub's state, so a later reconnect does not switch it back on.
     if (!on) registry.setConversation(sessionID, false)
     // (REC-01) Off ends the session's recordings (with a grace for the console's last batches); best effort.
     const tenant = registry.sessionTenant(sessionID)
     if (!on && tenant !== undefined) await recordingService.conversationChanged(tenant, sessionID, false).catch((cause) => console.error(`[hub] recording end failed: ${(cause as Error).message}`))
     const connID = ownerOf(sessionID)
-    const { agent } = await spokes.request(connID, { op: "conversation", sessionID, on })
-    if (on) registry.setConversation(sessionID, true, connID)
-    if (on && tenant !== undefined) recordingTap(sessionID, "conversation", { on: true })
-    return Response.json({ on, agent })
+    const sendFront = wantsFront && registry.supports(connID, "voiceFront")
+    // (voice front P1) Until the op answers, a "Voice: " session the spoke newly reports is not listed (the front).
+    if (sendFront) registry.frontOpStarted(connID)
+    let result: ResultFor["conversation"]
+    try {
+      result = await spokes.request(connID, { op: "conversation", sessionID, on, ...(sendFront ? { front: true } : {}) })
+      const frontID = sendFront && typeof result.front?.sessionID === "string" ? result.front.sessionID : null
+      if (on) registry.setConversation(sessionID, true, connID, wantsFront ? frontID : undefined)
+    } finally {
+      if (sendFront) registry.frontOpEnded(connID)
+    }
+    const front = registry.frontOf(sessionID) !== undefined
+    if (on && tenant !== undefined) recordingTap(sessionID, "conversation", { on: true, ...(wantsFront ? { front } : {}) })
+    return Response.json({ on, agent: result.agent, ...(wantsFront || (!on && hadFront) ? { front } : {}) })
   }
 
   /** Enables or disables voice for a session, through a process that reported it (service first). */
@@ -2819,6 +3064,16 @@ function prefsInput(value: unknown): (Partial<PushPrefs> & LegacyPushPrefs) | un
   return Object.keys(prefs).length ? prefs : undefined
 }
 
+/** PUT /api/settings/media body: {allowlist: hostnames or `*.suffix`es}, normalised (packages/protocol media-allowlist). */
+function mediaSettingsInput(value: unknown): string[] {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) throw new HttpError(400, "Expected {allowlist: [hostnames]}")
+  const record = value as Record<string, unknown>
+  if (Object.keys(record).some((key) => key !== "allowlist")) throw new HttpError(400, "Expected {allowlist: [hostnames]}")
+  const parsed = parseMediaAllowlist(record.allowlist)
+  if (!parsed.ok) throw new HttpError(400, parsed.reason)
+  return parsed.allowlist
+}
+
 /** PUT /api/prefs/view body: any of the four lists, each replacing the stored one. */
 function viewPrefsInput(value: unknown): Partial<ViewPrefs> {
   const invalid = () =>