@huynle/hub 0.8.6 → 0.9.0

package/src/central/artifacts/preview-bundle.ts

@@ -0,0 +1,81 @@
+// (Session media §3, item 4b) The hub's side of the spoke op previewBundle (packages/protocol/src/preview-bundle.ts):
+// the manifest first, then every file the spoke did not inline, chunk by chunk, each checked against the manifest
+// (sizes, SHA-256) before the preview is stored. A bundle that changes on the spoke while it is read (`stale`) is read
+// again from the start, a few times at most.
+import { createHash } from "node:crypto"
+import { PREVIEW_BUNDLE_LIMITS, previewBundleResultProblem, type PreviewBundleResult, type PreviewBundleSkip } from "../../protocol"
+import type { PreviewBundleContent } from "./store"
+
+/** One previewBundle request of the page (its message and path are the caller's): the manifest, or a chunk. */
+export type BundleAsk = (chunk?: { readonly bundle: string; readonly file: number; readonly offset: number }) => Promise<PreviewBundleResult>
+
+export type FetchedBundle =
+  | { readonly bundle: PreviewBundleContent; readonly skipped: readonly PreviewBundleSkip[]; readonly skippedMore?: number }
+  | { readonly error: "not_found" | "hidden" | "refused" | "changed" }
+  | { readonly error: "too_large"; readonly bytes: number; readonly max: number }
+
+/** A spoke answer that breaks the protocol (the route answers 502). */
+export class BundleProtocolError extends Error {}
+
+/** Reads of a bundle that keeps changing before the hub gives up ("changed"). */
+const ATTEMPTS = 3
+
+const sha256 = (bytes: Uint8Array) => createHash("sha256").update(bytes).digest("hex")
+
+function checked(result: unknown): PreviewBundleResult {
+  const problem = previewBundleResultProblem(result)
+  if (problem) throw new BundleProtocolError(`The spoke's preview bundle is malformed: ${problem}`)
+  return result as PreviewBundleResult
+}
+
+/** The page's bundle from the spoke (see the file's header). */
+export async function fetchPreviewBundle(ask: BundleAsk): Promise<FetchedBundle> {
+  for (let attempt = 0; attempt < ATTEMPTS; attempt++) {
+    const first = checked(await ask())
+    if (first.refused === "hidden") return { error: "hidden" }
+    if (first.refused !== undefined) return { error: "refused" }
+    if (first.tooLarge) return { error: "too_large", bytes: first.tooLarge.bytes, max: first.tooLarge.max }
+    if (first.bundle === undefined || first.files === undefined || first.entry === undefined) {
+      if (first.chunk !== undefined || first.stale !== undefined) throw new BundleProtocolError("The spoke answered a manifest request with a chunk")
+      return { error: "not_found" }
+    }
+    const total = first.files.reduce((n, f) => n + f.bytes, 0)
+    if (total > PREVIEW_BUNDLE_LIMITS.totalBytes) throw new BundleProtocolError("The spoke's preview bundle is over its total size cap")
+    const files: Array<{ path: string; mediaType: string; body: Uint8Array }> = []
+    let stale = false
+    for (const [index, file] of first.files.entries()) {
+      let body: Uint8Array
+      if (file.data !== undefined) body = Uint8Array.from(Buffer.from(file.data, "base64"))
+      else {
+        const read = await readChunks(ask, first.bundle, index, file.bytes)
+        if (read === "stale") {
+          stale = true
+          break
+        }
+        body = read
+      }
+      if (body.length !== file.bytes || sha256(body) !== file.sha256) throw new BundleProtocolError(`The spoke's file ${file.path} does not match its manifest`)
+      files.push({ path: file.path, mediaType: file.mediaType, body })
+    }
+    if (stale) continue
+    return { bundle: { entry: first.entry, files }, skipped: first.skipped ?? [], ...(first.skippedMore ? { skippedMore: first.skippedMore } : {}) }
+  }
+  return { error: "changed" }
+}
+
+/** A file's bytes in chunks from offset 0 (none for an empty file), or "stale". */
+async function readChunks(ask: BundleAsk, bundle: string, file: number, bytes: number): Promise<Uint8Array | "stale"> {
+  const out = new Uint8Array(bytes)
+  let offset = 0
+  while (offset < bytes) {
+    const answer = checked(await ask({ bundle, file, offset }))
+    if (answer.stale) return "stale"
+    const chunk = answer.chunk
+    if (!chunk || chunk.offset !== offset) throw new BundleProtocolError("The spoke answered a chunk request without that chunk")
+    const data = Buffer.from(chunk.data, "base64")
+    if (data.length === 0 || offset + data.length > bytes || chunk.last !== (offset + data.length === bytes)) throw new BundleProtocolError("The spoke's chunk does not fit its file")
+    out.set(data, offset)
+    offset += data.length
+  }
+  return out
+}

package/src/central/artifacts/previews.ts

@@ -0,0 +1,94 @@
+// HTML previews of code blocks in session messages (session media §3, item 4a). The hub reads the message itself,
+// from the session's spoke (the timeline op, newest-first pages), and never takes content from the console:
+//   - messageTexts: the text of one message's assistant text parts, in order (what the console renders as Markdown);
+//   - htmlBlocks: the fenced ```html / ```htm blocks of one text, parsed by the console's own Markdown parser
+//     (packages/protocol/src/markdown.ts, which web/src/lib/markdown.ts re-exports).
+// Block `n` counts html blocks across the message's text parts in order. The store keeps the block as a preview
+// artifact (ArtifactStore.savePreview).
+import type { TimelinePage } from "../../protocol"
+import { type MdBlock, parseMarkdown } from "../../../packages/protocol/src/markdown.ts"
+
+export const PREVIEW_LIMITS = {
+  /** Bytes of one previewed HTML block (413 above). */
+  htmlBytes: 2 * 1024 * 1024,
+  /**
+   * Timeline rows per page read (small, so a page of long replies stays under the spoke frame limit), and pages
+   * read before giving up on finding the message.
+   */
+  pageRows: 50,
+  pages: 40,
+} as const
+
+const HTML_LANGS = new Set(["html", "htm"])
+
+/**
+ * The fenced html/htm blocks of one text in document order (depth first through quotes and lists), parsed by the
+ * console's own Markdown parser: exactly the code blocks the console shows, with the same contents. The whole text
+ * is parsed (block numbers count from its start, so it cannot stop early): that parser is linear-time on adversarial
+ * text (test/web-markdown-perf.test.ts) and keeps blocks nested deeper than its MAX_BLOCK_DEPTH flat, as the console
+ * does.
+ */
+export function htmlBlocks(text: string): string[] {
+  const out: string[] = []
+  const walk = (blocks: readonly MdBlock[]): void => {
+    for (const b of blocks) {
+      if (b.type === "code" && HTML_LANGS.has(b.lang.toLowerCase())) out.push(b.text)
+      else if (b.type === "quote") walk(b.blocks)
+      else if (b.type === "list") for (const item of b.items) walk(item.blocks)
+    }
+  }
+  walk(parseMarkdown(text))
+  return out
+}
+
+/** A newest-first timeline page request (op "timeline", order desc). */
+export type TimelineReader = (page: { readonly limit: number; readonly before?: string }) => Promise<TimelinePage>
+
+const record = (v: unknown): Record<string, unknown> => (v && typeof v === "object" && !Array.isArray(v) ? (v as Record<string, unknown>) : {})
+
+/**
+ * The texts of the message's assistant text rows in order. Pages are read newest first until the message's rows
+ * are complete, at most PREVIEW_LIMITS.pages of them: a message older than that is "too_old" (not looked up, so a
+ * Preview never makes the spoke read a whole long history), one missing from the whole timeline "not_found".
+ */
+export async function messageTexts(read: TimelineReader, messageID: string): Promise<{ texts: string[] } | { error: "not_found" | "too_old" }> {
+  const rows: Array<{ text: string; order: number }> = []
+  let found = false
+  let exhausted = false
+  let complete = false
+  let before: string | undefined
+  for (let page = 0; page < PREVIEW_LIMITS.pages; page++) {
+    const result = await read({ limit: PREVIEW_LIMITS.pageRows, ...(before !== undefined ? { before } : {}) })
+    const items = Array.isArray(result?.items) ? result.items.map(record) : []
+    let mine = 0
+    items.forEach((item, index) => {
+      if (item.messageID !== messageID || item.kind === "message") return
+      mine++
+      if (item.kind === "assistant" && typeof item.text === "string") rows.push({ text: item.text, order: typeof item.pos === "number" ? item.pos : page * -1e6 + index })
+    })
+    if (mine > 0) found = true
+    // The message's rows are contiguous: done once a page holds rows before them, or there is nothing older.
+    const first = items[0]
+    if (typeof result?.older !== "string" || !result.older) {
+      exhausted = true
+      break
+    }
+    if (found && first?.messageID !== messageID) {
+      complete = true
+      break
+    }
+    before = result.older
+  }
+  if (!found) return { error: exhausted ? "not_found" : "too_old" }
+  // The cap cut the message's own rows: its block numbering would be wrong.
+  if (!complete && !exhausted) return { error: "too_old" }
+  return { texts: rows.sort((a, b) => a.order - b.order).map((r) => r.text) }
+}
+
+/** The `block`-th html block across the texts: its bytes, or why not (no such block, larger than `maxBytes`). */
+export function pickHtmlBlock(texts: readonly string[], block: number, maxBytes: number = PREVIEW_LIMITS.htmlBytes): { html: Uint8Array } | { error: "not_found" | "too_large" } {
+  const html = texts.flatMap(htmlBlocks)[block]
+  if (html === undefined) return { error: "not_found" }
+  const bytes = new TextEncoder().encode(html)
+  return bytes.byteLength > maxBytes ? { error: "too_large" } : { html: bytes }
+}

package/src/central/artifacts/routes.ts

@@ -1,7 +1,7 @@
 // The artifact transfer API (HWA-21; contract docs/plans/2026-10-30-hub-workspaces-artifacts-contracts.md, Artifacts),
 // under /api/agent with the agent error envelope:
 //
-//   GET    /artifacts                                  the caller's library (limit, cursor, state, workspace)
+//   GET    /artifacts                                  the caller's library (limit, cursor, state, workspace, origin)
 //   POST   /artifacts                                  create with the first revision (Idempotency-Key)
 //   POST   /artifacts/blobs                            stage raw bytes; answers a BlobRef to reference
 //   GET    /artifacts/:id                              one artifact
@@ -9,6 +9,7 @@
 //   DELETE /artifacts/:id                              irreversible {expectedRevision}
 //   PUT    /artifacts/:id/visibility                   {expectedRevision, visibility, workspaceID?}
 //   POST   /artifacts/:id/archive | /unarchive         {expectedRevision}
+//   POST   /artifacts/:id/keep                         {expectedRevision}: a preview becomes a normal artifact
 //   GET    /artifacts/:id/revisions                    newest first (limit, cursor)
 //   POST   /artifacts/:id/revisions                    {baseRevisionID, blobs|upload, entry?} (Idempotency-Key)
 //   GET    /artifacts/:id/revisions/:rev               one revision
@@ -227,11 +228,15 @@ export function artifactRoutes(deps: ArtifactRouteDeps): AgentRoute[] {
       const limit = intParam(url, "limit")
       const cursor = url.searchParams.get("cursor") ?? undefined
       const workspaceID = url.searchParams.get("workspace") ?? undefined
+      // Previews (session media §3) are listed only when asked for: origin=preview (only them) or origin=all.
+      const origin = url.searchParams.get("origin") ?? undefined
+      if (origin !== undefined && origin !== "preview" && origin !== "all") throw invalid("origin must be preview or all")
       const page = await store().list(user.id, principalOf(actor), {
         ...(limit !== undefined ? { limit } : {}),
         ...(cursor ? { cursor } : {}),
         ...(state ? { state: state as RecordState } : {}),
         ...(workspaceID ? { workspaceID } : {}),
+        ...(origin ? { origin: origin as "preview" | "all" } : {}),
       })
       return json(page)
     }),
@@ -318,6 +323,12 @@ export function artifactRoutes(deps: ArtifactRouteDeps): AgentRoute[] {
       }),
     ),
 
+    route("POST", `${P}/:id/keep`, MANAGE, async ({ user, actor, params, request }) => {
+      const body = await readJson(request, 4096)
+      onlyKeys(body, new Set(["expectedRevision"]), "The body")
+      return json({ artifact: await store().keep(user.id, principalOf(actor), params.id!, expectedRevision(body)) })
+    }),
+
     route("GET", `${P}/:id/revisions`, READ, async ({ user, actor, params, url }) => {
       const limit = intParam(url, "limit")
       const cursor = url.searchParams.get("cursor") ?? undefined

package/src/central/artifacts/store.ts

@@ -30,8 +30,10 @@
 //
 // Lifecycle: archive is reversible and keeps everything; delete is irreversible (tombstone first, so a crash half
 // way is finished by recover()); archived artifacts are purged only when `archivedRetentionMs` is set (default:
-// kept until deleted).
-import { randomBytes } from "node:crypto"
+// kept until deleted). Previews (origin "preview", session media §3) have their own retention in purgeArchived:
+// archived `previewArchiveAfterMs` after their last view (viewedAt, set when a host capability is minted) or
+// creation, purged `previewPurgeAfterMs` after that. Keep clears the origin, which ends it.
+import { createHash, randomBytes } from "node:crypto"
 import {
   ARTIFACT_LIMITS,
   ARTIFACT_MEDIA_TYPES,
@@ -41,10 +43,13 @@ import {
   type IdKind,
   isContractID,
   isExpectedRevision,
+  provenanceProblem,
   LIST_LIMIT_DEFAULT,
   LIST_LIMIT_MAX,
   type Artifact,
   type ArtifactKind,
+  type ArtifactOrigin,
+  type ArtifactProvenance,
   type ArtifactRevision,
   type ArtifactVisibility,
   type BlobRef,
@@ -64,6 +69,11 @@ export const UPLOADS = "artifact-uploads"
 export const revisionsCollection = (artifactID: string): string => `artifact-revisions.${artifactID}`
 /** How long an upload may run, and an unreferenced blob stays, before recovery treats it as abandoned. */
 export const ARTIFACT_GRACE_MS = 15 * 60_000
+/** Preview retention defaults: archived this long after the last view (or creation), then purged this long later. */
+export const PREVIEW_ARCHIVE_AFTER_MS = 24 * 60 * 60_000
+export const PREVIEW_PURGE_AFTER_MS = 7 * 24 * 60 * 60_000
+/** The single file of a preview revision. */
+export const PREVIEW_ENTRY = "index.html"
 /** CAS attempts on the artifact record when unrelated changes race a commit. */
 const ATTEMPTS = 16
 
@@ -98,8 +108,12 @@ export interface ArtifactStoreOptions {
   /** Tighter limits than ARTIFACT_LIMITS (never looser for blobBytes). */
   readonly limits?: Partial<ArtifactLimits>
   readonly graceMs?: number
-  /** Purge archived artifacts this long after archiving (default: never). */
+  /** Purge archived artifacts this long after archiving (default: never). Previews follow their own retention. */
   readonly archivedRetentionMs?: number
+  /** Archive a preview this long after its last view, or its creation when never viewed (default 24 h). */
+  readonly previewArchiveAfterMs?: number
+  /** Purge an archived preview this long after it was archived (default 7 days). */
+  readonly previewPurgeAfterMs?: number
   readonly onEvent?: (userID: string, event: ArtifactEvent) => void
   readonly newID?: (kind: IdKind) => string
 }
@@ -123,6 +137,9 @@ export interface ArtifactInput {
   readonly workspaceID?: string
   readonly tags?: readonly string[]
   readonly metadata?: Readonly<Record<string, string>>
+  /** Internal (savePreview): the routes never pass these. */
+  readonly origin?: ArtifactOrigin
+  readonly provenance?: ArtifactProvenance
 }
 
 export interface ArtifactUpdate {
@@ -139,6 +156,32 @@ export interface ArtifactListOptions {
   /** Default "active". */
   readonly state?: RecordState
   readonly workspaceID?: string
+  /** Default: normal artifacts only. "preview": previews only; "all": both. */
+  readonly origin?: ArtifactOrigin | "all"
+}
+
+/** The files of a preview revision and its entry (one of their paths). */
+export interface PreviewBundleContent {
+  readonly entry: string
+  readonly files: ReadonlyArray<{ readonly path: string; readonly mediaType: string; readonly body: Uint8Array }>
+}
+
+/** A stored copy of a provenance: only its known fields. */
+const provenanceCopy = (p: ArtifactProvenance): ArtifactProvenance => ({
+  sessionID: p.sessionID,
+  messageID: p.messageID,
+  ...(p.block !== undefined ? { block: p.block } : {}),
+  ...(p.path !== undefined ? { path: p.path } : {}),
+})
+
+/** "Preview: <file name>" for a page path, cut to the title limit. */
+const previewTitle = (path: string): string => `Preview: ${path.replace(/[\\/]+$/, "").split(/[\\/]/).pop() || path}`.slice(0, 120)
+
+export interface SavedPreview {
+  readonly artifact: Artifact
+  readonly revision: ArtifactRevision
+  /** The content was unchanged: the latest revision was reused. */
+  readonly reused: boolean
 }
 
 export interface RecoveryReport {
@@ -154,6 +197,8 @@ interface StoredArtifact {
   readonly head: number
   readonly archivedAt?: number
   readonly deletingAt?: number
+  /** Previews: the last time a host capability was minted for it (retention counts from it). */
+  readonly viewedAt?: number
 }
 
 interface Holder {
@@ -215,6 +260,10 @@ export class ArtifactStore {
   private readonly limits: ArtifactLimits
   private readonly graceMs: number
   private readonly archivedRetentionMs: number | undefined
+  private readonly previewArchiveAfterMs: number
+  private readonly previewPurgeAfterMs: number
+  /** savePreview calls in flight per user and block (one process): concurrent presses share one artifact. */
+  private readonly previewsInFlight = new Map<string, Promise<SavedPreview>>()
   private readonly onEvent: ((userID: string, event: ArtifactEvent) => void) | undefined
   private readonly newID: (kind: IdKind) => string
 
@@ -228,6 +277,8 @@ export class ArtifactStore {
     if (this.limits.blobBytes > ARTIFACT_LIMITS.blobBytes) throw new Error("limits.blobBytes exceeds ARTIFACT_LIMITS.blobBytes")
     this.graceMs = options.graceMs ?? ARTIFACT_GRACE_MS
     this.archivedRetentionMs = options.archivedRetentionMs
+    this.previewArchiveAfterMs = options.previewArchiveAfterMs ?? PREVIEW_ARCHIVE_AFTER_MS
+    this.previewPurgeAfterMs = options.previewPurgeAfterMs ?? PREVIEW_PURGE_AFTER_MS
     this.onEvent = options.onEvent
     this.newID = options.newID ?? randomID
   }
@@ -252,6 +303,7 @@ export class ArtifactStore {
       .map((entry) => entry.value)
       .filter((s) => s.deletingAt === undefined && s.artifact.state === state)
       .filter((s) => options.workspaceID === undefined || s.artifact.workspaceID === options.workspaceID)
+      .filter((s) => options.origin === "all" || s.artifact.origin === options.origin)
       .map((s) => s.artifact)
       .sort((a, b) => b.updatedAt - a.updatedAt || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
       .filter((a) => !after || a.updatedAt < after.updatedAt || (a.updatedAt === after.updatedAt && a.id > after.id))
@@ -332,6 +384,8 @@ export class ArtifactStore {
         latestRevisionID: rev.id,
         ...(input.tags !== undefined ? { tags: [...input.tags] } : {}),
         ...(input.metadata !== undefined ? { metadata: { ...input.metadata } } : {}),
+        ...(input.origin !== undefined ? { origin: input.origin } : {}),
+        ...(input.provenance !== undefined ? { provenance: provenanceCopy(input.provenance) } : {}),
         createdAt: at,
         updatedAt: at,
       }
@@ -428,14 +482,20 @@ export class ArtifactStore {
     await this.finishDelete(userID, id)
   }
 
-  /** Purges archived artifacts older than archivedRetentionMs (none when unset); resolves with their IDs. */
+  /**
+   * Retention, for one user: archives previews not viewed for previewArchiveAfterMs, then purges archived previews
+   * older than previewPurgeAfterMs and other archived artifacts older than archivedRetentionMs (never when unset);
+   * resolves with the purged IDs.
+   */
   async purgeArchived(userID: string): Promise<string[]> {
-    if (this.archivedRetentionMs === undefined) return []
-    const cutoff = this.now() - this.archivedRetentionMs
+    await this.archiveStalePreviews(userID)
+    const now = this.now()
+    const retention = (a: Artifact): number | undefined => (a.origin === "preview" ? this.previewPurgeAfterMs : this.archivedRetentionMs)
     const purged: string[] = []
     for (const entry of await this.state.list<StoredArtifact>(userID, ARTIFACTS)) {
       const s = entry.value
-      if (s.deletingAt !== undefined || s.artifact.state !== "archived" || s.archivedAt === undefined || s.archivedAt > cutoff) continue
+      const keep = retention(s.artifact)
+      if (keep === undefined || s.deletingAt !== undefined || s.artifact.state !== "archived" || s.archivedAt === undefined || s.archivedAt > now - keep) continue
       const marked = await this.state.put<StoredArtifact>(userID, ARTIFACTS, entry.key, { ...s, deletingAt: this.now() }, { ifVersion: entry.version })
       if (!marked.ok) continue
       await this.finishDelete(userID, entry.key)
@@ -444,6 +504,134 @@ export class ArtifactStore {
     return purged
   }
 
+  // ---- previews (session media §3) ------------------------------------------------------------------------
+
+  /**
+   * Stores an HTML preview for the user: a private html artifact with origin "preview" and its source as provenance.
+   * A code block (`block`) is one index.html file; a local page (`path`, session media §3 4b) is its bundle (files and
+   * entry). The same source again reuses the latest revision when the content is unchanged (the same files with the
+   * same hashes and types, in any order, and the same entry) and adds a revision otherwise; an archived preview is
+   * restored. A preview counts as viewed.
+   */
+  savePreview(userID: string, source: ArtifactProvenance, content: string | Uint8Array | PreviewBundleContent, options: { readonly title?: string } = {}): Promise<SavedPreview> {
+    const key = JSON.stringify([userID, source.sessionID, source.messageID, source.block ?? null, source.path ?? null])
+    const running = this.previewsInFlight.get(key)
+    const bundle: PreviewBundleContent =
+      typeof content === "string" || content instanceof Uint8Array
+        ? { entry: PREVIEW_ENTRY, files: [{ path: PREVIEW_ENTRY, mediaType: "text/html", body: typeof content === "string" ? new TextEncoder().encode(content) : content }] }
+        : content
+    const run = (running ?? Promise.resolve())
+      .catch(() => {})
+      .then(() => this.storePreview(userID, source, bundle, options.title))
+    const tracked = run.finally(() => {
+      if (this.previewsInFlight.get(key) === tracked) this.previewsInFlight.delete(key)
+    })
+    this.previewsInFlight.set(key, tracked)
+    return tracked
+  }
+
+  /**
+   * Records a view of a preview (a host capability was minted for it): its retention restarts, and an archived
+   * preview is restored, as pressing Preview again does. Anything else is left alone.
+   */
+  async markViewed(userID: string, artifactID: string): Promise<void> {
+    const entry = await this.state.get<StoredArtifact>(userID, ARTIFACTS, artifactID)
+    if (!entry || entry.value.deletingAt !== undefined || entry.value.artifact.origin !== "preview") return
+    await this.mutateStored(userID, artifactID, (s) => this.viewed(s), (s) => s.artifact.state === "archived").catch((error: unknown) => {
+      if (!(error instanceof AgentError && error.code === "not_found")) throw error
+    })
+  }
+
+  /** Keep: a preview becomes a normal artifact (origin cleared; provenance stays). A normal artifact is unchanged. */
+  async keep(userID: string, principal: ArtifactPrincipal, id: string, expectedRevision: number): Promise<Artifact> {
+    const { stored } = await this.load(userID, principal, id, "manage")
+    if (stored.artifact.origin === undefined) {
+      // Nothing to change, but a stale expectedRevision is a conflict as for every other change.
+      if (!isExpectedRevision(expectedRevision)) throw invalid("expectedRevision must be a non-negative integer")
+      if (stored.artifact.revision !== expectedRevision) throw conflict("expectedRevision is not the current revision", stored)
+      return stored.artifact
+    }
+    return this.mutate(userID, principal, id, expectedRevision, async (s) => {
+      const { origin: _, ...artifact } = s.artifact
+      const { viewedAt: _v, ...rest } = s
+      return { ...rest, artifact: artifact as Artifact }
+    })
+  }
+
+  private async storePreview(userID: string, source: ArtifactProvenance, bundle: PreviewBundleContent, title: string | undefined): Promise<SavedPreview> {
+    const defaultTitle = source.path !== undefined ? previewTitle(source.path) : `HTML preview ${(source.block ?? 0) + 1}`
+    const problem = provenanceProblem(source) ?? artifactInputProblem({ title: title ?? defaultTitle, kind: "html", origin: "preview", provenance: source })
+    if (problem) throw invalid(problem)
+    const files: RevisionFile[] = bundle.files.map((f) => ({ body: f.body, mediaType: f.mediaType, path: f.path }))
+    const hashes = new Map(bundle.files.map((f) => [f.path, `${f.mediaType} sha256:${createHash("sha256").update(f.body).digest("hex")}`]))
+    const found = (await this.state.list<StoredArtifact>(userID, ARTIFACTS)).find(
+      (e) =>
+        e.value.deletingAt === undefined &&
+        e.value.artifact.origin === "preview" &&
+        e.value.artifact.provenance?.sessionID === source.sessionID &&
+        e.value.artifact.provenance.messageID === source.messageID &&
+        e.value.artifact.provenance.block === source.block &&
+        e.value.artifact.provenance.path === source.path,
+    )
+    if (!found) {
+      const input: ArtifactInput = { title: title ?? defaultTitle, kind: "html", origin: "preview", provenance: source }
+      const created = await this.create(userID, { kind: "user" }, input, { files, entry: bundle.entry })
+      return { ...created, reused: false }
+    }
+    const id = found.key
+    // Viewed now (and restored when archived), so retention never takes it while the console opens it.
+    let artifact = await this.mutateStored(userID, id, (s) => this.viewed(s), (s) => s.artifact.state === "archived")
+    const latest = (await this.visibleRevisions(userID, (await this.state.get<StoredArtifact>(userID, ARTIFACTS, id))!.value))[0]
+    const same =
+      latest !== undefined &&
+      latest.entry === bundle.entry &&
+      latest.blobs.length === hashes.size &&
+      latest.blobs.every((b) => b.path !== undefined && hashes.get(b.path) === `${b.mediaType} ${b.hash}`)
+    if (same) return { artifact, revision: latest, reused: true }
+    const revised = await this.revise(userID, { kind: "user" }, id, { files, entry: bundle.entry, baseRevisionID: artifact.latestRevisionID })
+    artifact = revised.artifact
+    return { artifact, revision: revised.revision, reused: false }
+  }
+
+  /** A preview's record after a view: active again (when archived) with its retention clock restarted. */
+  private viewed(s: StoredArtifact): StoredArtifact {
+    if (s.artifact.origin !== "preview") return s
+    const { archivedAt: _, ...rest } = s
+    return { ...rest, viewedAt: this.now(), artifact: { ...s.artifact, state: "active" } }
+  }
+
+  /**
+   * A system change of a stored record (CAS-retried, no principal): `bump` says whether it is a visible change
+   * (revision and updatedAt move, as for a user's change; archive events are emitted by the caller).
+   */
+  private async mutateStored(userID: string, id: string, change: (s: StoredArtifact) => StoredArtifact, bump: (s: StoredArtifact) => boolean): Promise<Artifact> {
+    for (let attempt = 0; attempt < ATTEMPTS; attempt++) {
+      const entry = await this.state.get<StoredArtifact>(userID, ARTIFACTS, id)
+      if (!entry || entry.value.deletingAt !== undefined) throw notFound()
+      const visible = bump(entry.value)
+      const changed = change(entry.value)
+      const next: StoredArtifact = visible ? { ...changed, artifact: { ...changed.artifact, revision: entry.value.artifact.revision + 1, updatedAt: this.now() } } : changed
+      if ((await this.state.put<StoredArtifact>(userID, ARTIFACTS, id, next, { ifVersion: entry.version })).ok) {
+        if (visible && next.artifact.state !== entry.value.artifact.state) {
+          this.emit(userID, { type: "artifact.archived", artifactID: id, kind: next.artifact.kind, revision: next.artifact.revision, state: next.artifact.state })
+        }
+        return next.artifact
+      }
+    }
+    throw conflict("The artifact kept changing; retry", undefined)
+  }
+
+  /** Archives active previews whose last view (or creation) is older than previewArchiveAfterMs. */
+  private async archiveStalePreviews(userID: string): Promise<void> {
+    const cutoff = this.now() - this.previewArchiveAfterMs
+    for (const entry of await this.state.list<StoredArtifact>(userID, ARTIFACTS)) {
+      const s = entry.value
+      if (s.deletingAt !== undefined || s.artifact.origin !== "preview" || s.artifact.state !== "active" || (s.viewedAt ?? s.artifact.createdAt) > cutoff) continue
+      const stale = (c: StoredArtifact) => c.artifact.origin === "preview" && c.artifact.state === "active" && (c.viewedAt ?? c.artifact.createdAt) <= cutoff
+      await this.mutateStored(userID, entry.key, (c) => (stale(c) ? { ...c, archivedAt: this.now(), artifact: { ...c.artifact, state: "archived" } } : c), stale).catch(() => {})
+    }
+  }
+
   // ---- recovery -------------------------------------------------------------------------------------------
 
   /**
@@ -705,7 +893,9 @@ export class ArtifactStore {
   private async setState(userID: string, principal: ArtifactPrincipal, id: string, expectedRevision: number, to: RecordState): Promise<Artifact> {
     const artifact = await this.mutate(userID, principal, id, expectedRevision, async (s) => {
       const { archivedAt: _, ...rest } = s
-      return { ...rest, ...(to === "archived" ? { archivedAt: this.now() } : {}), artifact: { ...s.artifact, state: to } }
+      // Unarchiving a preview restarts its retention, so the next maintenance pass does not archive it again.
+      const viewed = to === "active" && s.artifact.origin === "preview" ? { viewedAt: this.now() } : {}
+      return { ...rest, ...viewed, ...(to === "archived" ? { archivedAt: this.now() } : {}), artifact: { ...s.artifact, state: to } }
     })
     this.emit(userID, { type: "artifact.archived", artifactID: id, kind: artifact.kind, revision: artifact.revision, state: to })
     return artifact

package/src/central/config.ts

@@ -11,6 +11,7 @@ import { APP_DIR, configBase, legacyPaths, migrateFirst, migrateStateDir, resolv
 import { updateSpeech, type StoredSpeech } from "./speech/settings"
 import { checkReleaseBase } from "./install/render"
 import { cspMode, type CspMode } from "./csp"
+import { parseDenyCidrs } from "./fetcher"
 
 export const GOOGLE_ISSUER = "https://accounts.google.com"
 
@@ -77,6 +78,10 @@ export interface CentralConfig {
   readonly releaseBase?: string
   /** Cluster mode (design §9): set only when HUB_DATABASE_URL and HUB_VALKEY_URL (or hub.json cluster) are. */
   readonly cluster?: ClusterConfig
+  /** HUB_REMOTE_FETCH=off (only then set, to false): turns off the hub fetching web URLs for the console (/api/media/remote, /api/media/unfurl). */
+  readonly remoteFetch?: boolean
+  /** HUB_FETCH_DENY_CIDRS: CIDRs the hub's outbound fetcher refuses on top of its built-in ranges (validated). */
+  readonly fetchDenyCidrs?: readonly string[]
 }
 
 /**
@@ -469,6 +474,28 @@ function clusterConfig(env: Env, auth: AuthConfig, file: HubCluster = {}): Clust
   return cluster as ClusterConfig
 }
 
+const PROXY_VARS = ["HTTP_PROXY", "HTTPS_PROXY", "http_proxy", "https_proxy"] as const
+
+/**
+ * HUB_REMOTE_FETCH: "on", "off", or unset. Unset means on, unless a proxy is set in the environment (Bun's fetch
+ * honours HTTP(S)_PROXY with no per-request opt-out, and a proxy may re-resolve the name, undoing the fetcher's
+ * address pinning) and NO_PROXY is not "*": then off, with a startup warning. Throws on any other value.
+ */
+export function remoteFetchSetting(rawEnv: Env): { enabled: boolean; warning?: string } {
+  const raw = rawEnv.HUB_REMOTE_FETCH
+  const value = raw?.trim().toLowerCase()
+  if (value === "on") return { enabled: true }
+  if (value === "off") return { enabled: false }
+  if (value) throw new Error(`HUB_REMOTE_FETCH must be "on" or "off", got ${JSON.stringify(raw)}`)
+  const proxy = PROXY_VARS.find((name) => rawEnv[name]?.trim())
+  const noProxy = (rawEnv.NO_PROXY ?? rawEnv.no_proxy)?.trim()
+  if (!proxy || noProxy === "*") return { enabled: true }
+  return {
+    enabled: false,
+    warning: `remote images are off (HUB_REMOTE_FETCH): ${proxy} is set, and a proxy could re-resolve hostnames and reach private addresses. Set NO_PROXY=* for the hub process to fetch directly, or HUB_REMOTE_FETCH=on to accept proxying knowingly`,
+  }
+}
+
 export function centralConfig(rawEnv: Env = process.env, home: string = homedir(), file: HubFile = {}): CentralConfig {
   const env = hubEnv(rawEnv)
   const host = env.HUB_HOST || file.host || "127.0.0.1"
@@ -486,6 +513,9 @@ export function centralConfig(rawEnv: Env = process.env, home: string = homedir(
   }
   const auth = authConfig(env, file.auth)
   const cluster = clusterConfig(env, auth, file.cluster)
+  const remoteFetch = remoteFetchSetting(env).enabled ? "on" : "off"
+  parseDenyCidrs(env.HUB_FETCH_DENY_CIDRS) // throws on an invalid entry: a startup error
+  const fetchDenyCidrs = (env.HUB_FETCH_DENY_CIDRS ?? "").split(",").map((entry) => entry.trim()).filter(Boolean)
   return {
     host,
     port,
@@ -508,6 +538,8 @@ export function centralConfig(rawEnv: Env = process.env, home: string = homedir(
     ...(file.agents?.webhooks?.allowPrivate === true ? { webhooksAllowPrivate: true as const } : {}),
     ...(releaseBase ? { releaseBase } : {}),
     ...(cluster ? { cluster } : {}),
+    ...(remoteFetch === "off" ? { remoteFetch: false } : {}),
+    ...(fetchDenyCidrs.length ? { fetchDenyCidrs } : {}),
   }
 }
 
@@ -532,6 +564,8 @@ export function loadCentralConfig(
   if (!resolved.HUB_CONFIG) migrateFirst(legacyPaths(configBase(env, home), "hub.json"), file, migrate)
   const { file: hub, warnings } = readHubFile(file, home)
   const config = centralConfig(env, home, hub)
+  const remoteFetchWarning = remoteFetchSetting(hubEnv(env)).warning
+  if (remoteFetchWarning) warnings.push(remoteFetchWarning)
   if (!resolved.HUB_STATE_DIR && !hub?.stateDir) {
     // hub.pid is the spoke's auto-start lock for the legacy location, not state.
     migrateStateDir(stateLegacyPaths(env, home), config.stateDir, { ...migrate, skip: ["hub.pid"] })