@huynle/hub 0.8.6 → 0.9.0

package/packages/protocol/src/media-allowlist.ts

@@ -0,0 +1,240 @@
+// (RF2, session media §4) The per-user media allowlist: hostnames (`github.com`) or suffixes
+// (`*.githubusercontent.com`) whose web images the console loads at once through GET /api/media/remote. Shared by
+// the hub (PUT /api/settings/media validates with parseMediaAllowlist) and the console (Settings → Media, and the
+// match for a reply's image). Entries are stored normalised: lowercase, no trailing dot, IDNs as punycode. Refused:
+// IP addresses, ports, schemes, paths, userinfo, a bare `*`, and wildcards (or exact hosts) that are only a public
+// suffix (`*.com`, `*.co.uk`, `*.github.io`): a wildcard needs at least two labels after `*.`, none of them a known
+// public suffix. A wildcard matches subdomains only, never the suffix itself.
+
+export const MEDIA_ALLOWLIST_LIMITS = { entries: 100, chars: 253 } as const
+
+/**
+ * Common public suffixes of more than one label (and shared hosting suffixes whose subdomains belong to different
+ * owners). Single-label suffixes (`com`, `de` …) are refused by the two-label rule. Not the full Public Suffix List:
+ * a small built-in guard against the obvious mistakes.
+ */
+const PUBLIC_SUFFIXES = new Set([
+  ...["co", "org", "ac", "gov", "net", "me", "ltd", "plc", "sch", "nhs"].map((s) => `${s}.uk`),
+  ...["com", "net", "org", "edu", "gov", "id", "asn"].map((s) => `${s}.au`),
+  ...["co", "ne", "or", "ac", "go", "gr", "ed", "ad", "lg"].map((s) => `${s}.jp`),
+  ...["co", "org", "net", "ac", "govt", "school", "geek", "gen", "kiwi", "maori"].map((s) => `${s}.nz`),
+  ...["com", "net", "org", "gov", "edu"].map((s) => `${s}.br`),
+  ...["com", "net", "org", "gov", "edu", "ac"].map((s) => `${s}.cn`),
+  ...["com", "net", "org", "gob", "edu"].map((s) => `${s}.mx`),
+  ...["co", "net", "org", "firm", "gen", "ind", "ac", "edu", "gov", "res"].map((s) => `${s}.in`),
+  ...["co", "org", "net", "ac", "gov", "web"].map((s) => `${s}.za`),
+  ...["com", "net", "org", "gov", "edu"].map((s) => `${s}.tr`),
+  ...["com", "net", "org", "gov", "edu"].map((s) => `${s}.sg`),
+  ...["com", "net", "org", "gov", "edu"].map((s) => `${s}.hk`),
+  ...["co", "or", "ne", "go", "ac", "re"].map((s) => `${s}.kr`),
+  ...["com", "net", "org", "gov", "edu"].map((s) => `${s}.tw`),
+  ...["com", "net", "org", "gov", "edu"].map((s) => `${s}.ar`),
+  ...["co", "or", "ac", "go"].map((s) => `${s}.id`),
+  ...["co", "or", "ac", "go"].map((s) => `${s}.th`),
+  ...["com", "net", "org", "gov", "edu"].map((s) => `${s}.my`),
+  ...["com", "net", "org", "gov", "edu"].map((s) => `${s}.ph`),
+  ...["com", "net", "org", "gov", "edu"].map((s) => `${s}.pk`),
+  ...["com", "net", "org", "gov", "edu"].map((s) => `${s}.ua`),
+  ...["com", "net", "org", "gov", "edu"].map((s) => `${s}.pl`),
+  ...["co", "or", "ac"].map((s) => `${s}.at`),
+  ...["co", "org", "ac"].map((s) => `${s}.il`),
+  "com.es",
+  "org.es",
+  "co.it",
+  "com.ru",
+  "co.ca",
+  "eu.org",
+  // Shared hosting: every subdomain is someone else's site.
+  "github.io",
+  "githubpreview.dev",
+  "gitlab.io",
+  "pages.dev",
+  "workers.dev",
+  "netlify.app",
+  "vercel.app",
+  "herokuapp.com",
+  "appspot.com",
+  "blogspot.com",
+  "cloudfront.net",
+  "azurewebsites.net",
+  "web.app",
+  "firebaseapp.com",
+  "s3.amazonaws.com",
+  "ngrok.io",
+  "ngrok-free.app",
+  "glitch.me",
+  "repl.co",
+  "fly.dev",
+  "onrender.com",
+])
+
+const LABEL = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/
+
+type Entry = { ok: true; entry: string } | { ok: false; reason: string }
+
+/** One allowlist entry, normalised (lowercase, no trailing dot, punycode), or why it is refused. */
+export function normalizeAllowlistEntry(raw: string): Entry {
+  if (typeof raw !== "string") return { ok: false, reason: "Expected a hostname" }
+  const value = raw.trim()
+  if (!value) return { ok: false, reason: "Expected a hostname" }
+  if (value.length > MEDIA_ALLOWLIST_LIMITS.chars)
+    return {
+      ok: false,
+      reason: `${short(value)}: at most ${MEDIA_ALLOWLIST_LIMITS.chars} characters`,
+    }
+  if (/[\s/\\:@?#[\]%]/.test(value))
+    return {
+      ok: false,
+      reason: `${short(value)}: a hostname only (no scheme, port, path or address)`,
+    }
+  const wildcard = value.startsWith("*.")
+  const rest = wildcard ? value.slice(2) : value
+  if (rest.includes("*"))
+    return {
+      ok: false,
+      reason: `${short(value)}: a wildcard only as a leading "*."`,
+    }
+  const ascii = toASCII(rest.replace(/\.$/, ""))
+  if (ascii === undefined) return { ok: false, reason: `${short(value)}: not a hostname` }
+  const labels = ascii.split(".")
+  if (labels.some((l) => !LABEL.test(l))) return { ok: false, reason: `${short(value)}: not a hostname` }
+  if (/^\d+$/.test(labels[labels.length - 1]!))
+    return {
+      ok: false,
+      reason: `${short(value)}: an IP address or numeric domain is not allowed`,
+    }
+  if (labels.length < 2)
+    return {
+      ok: false,
+      reason: wildcard ? `${short(value)}: too broad (name at least two labels after "*.")` : `${short(value)}: name a full hostname (like github.com)`,
+    }
+  if (PUBLIC_SUFFIXES.has(ascii))
+    return {
+      ok: false,
+      reason: `${short(value)}: too broad (a public suffix: name the site itself)`,
+    }
+  const entry = wildcard ? `*.${ascii}` : ascii
+  if (entry.length > MEDIA_ALLOWLIST_LIMITS.chars)
+    return {
+      ok: false,
+      reason: `${short(value)}: at most ${MEDIA_ALLOWLIST_LIMITS.chars} characters`,
+    }
+  return { ok: true, entry }
+}
+
+const short = (value: string) => (value.length > 60 ? `${value.slice(0, 57)}…` : value)
+
+/** A host in punycode through the URL parser (which also lowercases); undefined when it is not a valid one. */
+function toASCII(host: string): string | undefined {
+  if (!host) return undefined
+  try {
+    const parsed = new URL(`http://${host}/`)
+    return parsed.hostname && parsed.hostname === parsed.host ? parsed.hostname : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** The whole setting (PUT /api/settings/media's `allowlist`): normalised, order kept, duplicates dropped. */
+export function parseMediaAllowlist(value: unknown): { ok: true; allowlist: string[] } | { ok: false; reason: string } {
+  if (!Array.isArray(value)) return { ok: false, reason: "Expected allowlist: a list of hostnames" }
+  if (value.length > MEDIA_ALLOWLIST_LIMITS.entries)
+    return {
+      ok: false,
+      reason: `At most ${MEDIA_ALLOWLIST_LIMITS.entries} allowed sites`,
+    }
+  const out: string[] = []
+  for (const raw of value) {
+    const entry = normalizeAllowlistEntry(raw as string)
+    if (!entry.ok) return entry
+    if (!out.includes(entry.entry)) out.push(entry.entry)
+  }
+  return { ok: true, allowlist: out }
+}
+
+/**
+ * The hostname of an http(s) image URL, normalised like allowlist entries (the URL parser's host: lowercase,
+ * punycode, userinfo dropped); undefined for other schemes, unparsable URLs and ports other than 80/443 (the hub's
+ * fetcher refuses those).
+ */
+export function imageHost(url: string): string | undefined {
+  let parsed: URL
+  try {
+    parsed = new URL(url)
+  } catch {
+    return undefined
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return undefined
+  if (parsed.port && parsed.port !== "80" && parsed.port !== "443") return undefined
+  return parsed.hostname.replace(/\.$/, "") || undefined
+}
+
+/** Whether a host is on the allowlist: an exact entry, or a `*.suffix` entry for a subdomain of it. */
+export function allowlistMatches(allowlist: readonly string[], host: string): boolean {
+  const h = host.toLowerCase().replace(/\.$/, "")
+  if (!h) return false
+  return allowlist.some((entry) => (entry.startsWith("*.") ? h.endsWith(entry.slice(1)) && h.length > entry.length - 1 : h === entry))
+}
+
+/** A host with its punycode labels shown in unicode (for display next to the punycode form). */
+export function hostUnicode(host: string): string {
+  return host
+    .split(".")
+    .map((label) => {
+      if (!label.toLowerCase().startsWith("xn--")) return label
+      return decodePunycode(label.slice(4)) ?? label
+    })
+    .join(".")
+}
+
+/** RFC 3492 decoding of one label's punycode (after "xn--"); undefined when it is not valid. */
+function decodePunycode(input: string): string | undefined {
+  const base = 36
+  const tMin = 1
+  const tMax = 26
+  const skew = 38
+  const damp = 700
+  let n = 128
+  let i = 0
+  let bias = 72
+  const delimiter = input.lastIndexOf("-")
+  const output: number[] = []
+  for (let j = 0; j < Math.max(delimiter, 0); j++) {
+    const c = input.charCodeAt(j)
+    if (c >= 0x80) return undefined
+    output.push(c)
+  }
+  const adapt = (delta: number, points: number, first: boolean) => {
+    delta = first ? Math.floor(delta / damp) : delta >> 1
+    delta += Math.floor(delta / points)
+    let k = 0
+    while (delta > ((base - tMin) * tMax) >> 1) {
+      delta = Math.floor(delta / (base - tMin))
+      k += base
+    }
+    return k + Math.floor(((base - tMin + 1) * delta) / (delta + skew))
+  }
+  const digit = (c: number) => (c >= 48 && c <= 57 ? c - 22 : c >= 65 && c <= 90 ? c - 65 : c >= 97 && c <= 122 ? c - 97 : base)
+  for (let at = delimiter > 0 ? delimiter + 1 : 0; at < input.length;) {
+    const old = i
+    for (let w = 1, k = base; ; k += base) {
+      if (at >= input.length) return undefined
+      const d = digit(input.charCodeAt(at++))
+      if (d >= base) return undefined
+      i += d * w
+      const t = k <= bias ? tMin : k >= bias + tMax ? tMax : k - bias
+      if (d < t) break
+      w *= base - t
+    }
+    bias = adapt(i - old, output.length + 1, old === 0)
+    n += Math.floor(i / (output.length + 1))
+    i %= output.length + 1
+    if (n > 0x10ffff) return undefined
+    output.splice(i++, 0, n)
+  }
+  try {
+    return String.fromCodePoint(...output)
+  } catch {
+    return undefined
+  }
+}

package/packages/protocol/src/media.ts

@@ -0,0 +1,120 @@
+/**
+ * (S4 M2) Media in sessions: images a session shows that the console pulls on demand through the spoke op
+ * `timelineMedia` (feature "timelineMedia", announced, never implied). An image is named by its message and a ref:
+ *
+ * - `f<n>`: the n-th file attached to a user message (the same files `timelineFile` serves)
+ * - `t<part>.<item>`: content item `item` of the tool part at index `part` of an assistant message
+ * - `p:<base64url path>`: an image path written in an assistant message's text (`![alt](path)`), exactly as written;
+ *   the spoke re-reads the message and serves the file only under its path policy (src/spoke/media-policy.ts)
+ *
+ * The bytes travel in chunks of at most MEDIA_LIMITS.chunkBytes; the first answer (offset 0) carries the image's
+ * metadata, each answer the chunk at `offset` and whether it is the last.
+ */
+
+export const MEDIA_LIMITS = {
+  /** Largest image served (decoded bytes). */
+  maxBytes: 8 * 1024 * 1024,
+  /** Most pixels (width × height) of a raster image. */
+  maxPixels: 40_000_000,
+  /** Widest or tallest raster image, in pixels. */
+  maxSide: 16_384,
+  /** Largest chunk of one answer (decoded bytes). */
+  chunkBytes: 512 * 1024,
+  /** Most media a timeline row lists. */
+  perRow: 8,
+} as const
+
+/** The image types served: magic bytes must match. SVG is served only as an attachment (never a document). */
+export const MEDIA_MIMES = ["image/png", "image/jpeg", "image/webp", "image/gif", "image/svg+xml"] as const
+export type MediaMime = (typeof MEDIA_MIMES)[number]
+
+/** Longest path a `p:` ref carries (UTF-8 bytes). */
+export const MEDIA_PATH_MAX = 4096
+/** Longest ref (a `p:` ref of the longest path). */
+export const MEDIA_REF_MAX = 2 + Math.ceil((MEDIA_PATH_MAX * 4) / 3) + 4
+
+export type MediaRef =
+  | { readonly kind: "file"; readonly index: number }
+  | { readonly kind: "tool"; readonly part: number; readonly item: number }
+  | { readonly kind: "path"; readonly path: string }
+
+/** What a served image is. `width`/`height`: from its header (raster types). */
+export interface MediaInfo {
+  readonly mime: MediaMime
+  readonly bytes: number
+  /** Hex SHA-256 of the bytes. */
+  readonly sha256: string
+  readonly width?: number
+  readonly height?: number
+}
+
+export interface MediaChunk {
+  readonly offset: number
+  /** Base64 of at most MEDIA_LIMITS.chunkBytes bytes. */
+  readonly data: string
+  readonly last: boolean
+}
+
+/** Why an image is not served: not an allowed type, its message is hidden by a revert, too many pixels, a path outside the policy. */
+export const MEDIA_REFUSALS = ["type", "hidden", "dimensions", "path"] as const
+export type MediaRefusal = (typeof MEDIA_REFUSALS)[number]
+
+/**
+ * A timelineMedia answer: `media` and `chunk` when served; `tooLarge` when it exceeds MEDIA_LIMITS.maxBytes;
+ * `refused` with the reason; nothing at all when there is no such image.
+ */
+export interface TimelineMediaResult {
+  readonly media?: MediaInfo
+  readonly chunk?: MediaChunk
+  readonly tooLarge?: { readonly bytes: number; readonly max: number }
+  readonly refused?: MediaRefusal
+}
+
+const FILE_REF = /^f(0|[1-9]\d{0,2})$/
+const TOOL_REF = /^t(0|[1-9]\d{0,3})\.(0|[1-9]\d{0,2})$/
+const PATH_REF = /^p:([A-Za-z0-9_-]+)$/
+
+function base64url(bytes: Uint8Array): string {
+  let binary = ""
+  for (const byte of bytes) binary += String.fromCharCode(byte)
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "")
+}
+
+function fromBase64url(text: string): Uint8Array | undefined {
+  if (text.length % 4 === 1) return undefined
+  try {
+    const binary = atob(text.replace(/-/g, "+").replace(/_/g, "/"))
+    return Uint8Array.from(binary, (c) => c.charCodeAt(0))
+  } catch {
+    return undefined
+  }
+}
+
+/** The `p:` ref of a path as written in a message. */
+export function mediaPathRef(path: string): string {
+  return `p:${base64url(new TextEncoder().encode(path))}`
+}
+
+/** A ref's parts, or undefined when it is not a well-formed ref. */
+export function parseMediaRef(ref: string): MediaRef | undefined {
+  if (typeof ref !== "string" || ref.length > MEDIA_REF_MAX) return undefined
+  const file = FILE_REF.exec(ref)
+  if (file) return { kind: "file", index: Number(file[1]) }
+  const tool = TOOL_REF.exec(ref)
+  if (tool) return { kind: "tool", part: Number(tool[1]), item: Number(tool[2]) }
+  const path = PATH_REF.exec(ref)
+  if (!path) return undefined
+  const bytes = fromBase64url(path[1]!)
+  if (!bytes || bytes.length === 0 || bytes.length > MEDIA_PATH_MAX) return undefined
+  let text: string
+  try {
+    text = new TextDecoder("utf-8", { fatal: true }).decode(bytes)
+  } catch {
+    return undefined
+  }
+  if (text.includes("\u0000") || mediaPathRef(text) !== ref) return undefined
+  return { kind: "path", path: text }
+}
+
+/** Whether `offset` is a valid chunk offset of a timelineMedia request. */
+export const isMediaOffset = (offset: unknown): boolean => Number.isInteger(offset) && (offset as number) >= 0 && (offset as number) <= MEDIA_LIMITS.maxBytes

package/packages/protocol/src/preview-bundle.ts

@@ -0,0 +1,221 @@
+/**
+ * (Session media §3, item 4b) Previews of local HTML files. The console names a page only by a path written in an
+ * assistant message (`htmlTargets`: a code span or a same-site path link ending in .html/.htm); the spoke re-reads the
+ * message, opens the page under the media path policy (src/spoke/media-policy.ts) and collects the files it refers to
+ * (src/spoke/preview-bundle.ts). Feature "previewBundle" (announced by the OpenCode spoke, never implied).
+ *
+ * Paging (a frame holds at most MAX_FRAME characters): the first request (`{sessionID, messageID, path}`) answers the
+ * bundle's manifest: `bundle` (its identity, a hex SHA-256 of the entry and every file's path, type and hash),
+ * `entry`, `files` and `skipped`. Files are inlined (`data`, base64) in manifest order while their decoded bytes fit
+ * in PREVIEW_BUNDLE_LIMITS.inlineBytes; every other file is read with `{bundle, file, offset}` requests, one chunk of at
+ * most chunkBytes each (`chunk: {offset, data, last}`). The spoke keeps the walked bundle for a minute; when it has to
+ * walk again and the bundle changed, a chunk request answers `stale: true` and the hub starts over.
+ */
+import type { Inline, MdBlock } from "./markdown.ts"
+
+export const PREVIEW_BUNDLE_FEATURE = "previewBundle"
+
+export const PREVIEW_BUNDLE_LIMITS = {
+  /** Most files in a bundle, the entry included. */
+  files: 200,
+  /** Largest file (the entry over it: tooLarge; an asset over it: skipped). */
+  fileBytes: 5 * 1024 * 1024,
+  /** Largest bundle (assets past it are skipped). */
+  totalBytes: 20 * 1024 * 1024,
+  /** Largest chunk of a chunk answer (decoded bytes). */
+  chunkBytes: 512 * 1024,
+  /** Decoded bytes inlined in the first answer. */
+  inlineBytes: 384 * 1024,
+  /** Longest path in a bundle (the artifact store's limit). */
+  bundlePathMax: 200,
+  /** Longest page path a request names. */
+  pathMax: 4096,
+  /** Longest reference listed as skipped (longer ones are cut). */
+  refMax: 300,
+  /** Most skipped references listed (`skippedMore` counts the rest). */
+  skipped: 200,
+} as const
+
+/** Why a referenced file is not in the bundle. */
+export const PREVIEW_SKIP_REASONS = ["missing", "refused", "too_large", "limit", "name", "type"] as const
+export type PreviewSkipReason = (typeof PREVIEW_SKIP_REASONS)[number]
+
+/** Why the page itself is not served: not in the policy (or not in the message), not an HTML file, hidden by a revert. */
+export const PREVIEW_BUNDLE_REFUSALS = ["path", "type", "hidden"] as const
+export type PreviewBundleRefusal = (typeof PREVIEW_BUNDLE_REFUSALS)[number]
+
+/**
+ * Media types by file extension, all of them artifact store types (ARTIFACT_MEDIA_TYPES: the store takes no other and
+ * never sniffs). A file of any other type (fonts, video, …) is left out of a bundle (skipped "type").
+ */
+export const PREVIEW_MEDIA_TYPES: Readonly<Record<string, string>> = {
+  html: "text/html",
+  htm: "text/html",
+  css: "text/css",
+  js: "text/javascript",
+  mjs: "text/javascript",
+  json: "application/json",
+  txt: "text/plain",
+  csv: "text/csv",
+  md: "text/markdown",
+  pdf: "application/pdf",
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  svg: "image/svg+xml",
+}
+
+/** The media type a bundle file gets from its name (undefined: not one a bundle carries). */
+export function previewMediaType(path: string): string | undefined {
+  const name = path.slice(path.lastIndexOf("/") + 1)
+  const dot = name.lastIndexOf(".")
+  const ext = dot > 0 ? name.slice(dot + 1).toLowerCase() : ""
+  return Object.hasOwn(PREVIEW_MEDIA_TYPES, ext) ? PREVIEW_MEDIA_TYPES[ext] : undefined
+}
+
+const MEDIA_TYPES = new Set(Object.values(PREVIEW_MEDIA_TYPES))
+
+/** A path inside a bundle: relative, no `.`/`..` segments or `//`, the artifact host's characters, ≤ 200. */
+export const isBundlePath = (v: unknown): v is string =>
+  typeof v === "string" && /^(?!\/)(?!.*(?:^|\/)\.\.?(?:\/|$))(?!.*\/\/)(?!.*\/$)[A-Za-z0-9._/-]{1,200}$/.test(v)
+
+export interface PreviewBundleFile {
+  readonly path: string
+  readonly mediaType: string
+  readonly bytes: number
+  /** Hex SHA-256 of the bytes. */
+  readonly sha256: string
+  /** Base64 of the bytes, when inlined in the first answer. */
+  readonly data?: string
+}
+
+export interface PreviewBundleSkip {
+  /** The reference as written (without its query or fragment; cut at PREVIEW_BUNDLE_LIMITS.refMax). */
+  readonly path: string
+  readonly reason: PreviewSkipReason
+}
+
+export interface PreviewBundleRequest {
+  readonly op: "previewBundle"
+  readonly sessionID: string
+  readonly messageID: string
+  /** The page as written in the message (a code span or link target). */
+  readonly path: string
+  /** A chunk request: the bundle's identity, the file's index in `files`, and the chunk's offset (all three or none). */
+  readonly bundle?: string
+  readonly file?: number
+  readonly offset?: number
+}
+
+/**
+ * A previewBundle answer: the manifest (bundle, entry, files, skipped), a chunk, `stale`, `tooLarge` (the page itself
+ * is over fileBytes), `refused`, or nothing at all (no such message).
+ */
+export interface PreviewBundleResult {
+  readonly bundle?: string
+  readonly entry?: string
+  readonly files?: readonly PreviewBundleFile[]
+  readonly skipped?: readonly PreviewBundleSkip[]
+  readonly skippedMore?: number
+  readonly chunk?: { readonly offset: number; readonly data: string; readonly last: boolean }
+  readonly stale?: true
+  readonly tooLarge?: { readonly bytes: number; readonly max: number }
+  readonly refused?: PreviewBundleRefusal
+}
+
+const HEX64 = /^[0-9a-f]{64}$/
+const isObj = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+const int = (v: unknown, min: number, max: number): v is number => Number.isSafeInteger(v) && (v as number) >= min && (v as number) <= max
+
+/** A page path as a request carries it: 1–pathMax characters, no NUL or line break. */
+export const isPreviewPath = (v: unknown): v is string => typeof v === "string" && v.length > 0 && v.length <= PREVIEW_BUNDLE_LIMITS.pathMax && !/[\u0000\r\n]/.test(v)
+
+/** Whether a previewBundle request is well-formed (index.ts parseServerMessage). */
+export function isPreviewBundleRequest(v: Record<string, unknown>): boolean {
+  if (typeof v.sessionID !== "string" || !v.sessionID) return false
+  if (typeof v.messageID !== "string" || !v.messageID || v.messageID.length > 300) return false
+  if (!isPreviewPath(v.path)) return false
+  const chunk = [v.bundle, v.file, v.offset].filter((x) => x !== undefined).length
+  if (chunk === 0) return true
+  return chunk === 3 && typeof v.bundle === "string" && HEX64.test(v.bundle) && int(v.file, 0, PREVIEW_BUNDLE_LIMITS.files - 1) && int(v.offset, 0, PREVIEW_BUNDLE_LIMITS.fileBytes - 1)
+}
+
+/** The problem with a previewBundle answer's shape (undefined: none). */
+export function previewBundleResultProblem(v: unknown): string | undefined {
+  if (!isObj(v)) return "must be an object"
+  const manifest = v.bundle !== undefined || v.entry !== undefined || v.files !== undefined || v.skipped !== undefined
+  const kinds = [manifest, v.chunk !== undefined, v.stale !== undefined, v.tooLarge !== undefined, v.refused !== undefined].filter(Boolean).length
+  if (kinds > 1) return "carries more than one of a manifest, chunk, stale, tooLarge and refused"
+  if (v.refused !== undefined && !(PREVIEW_BUNDLE_REFUSALS as readonly unknown[]).includes(v.refused)) return "refused must be path, type or hidden"
+  if (v.stale !== undefined && v.stale !== true) return "stale must be true"
+  if (v.tooLarge !== undefined && !(isObj(v.tooLarge) && int(v.tooLarge.bytes, 0, Number.MAX_SAFE_INTEGER) && int(v.tooLarge.max, 0, Number.MAX_SAFE_INTEGER))) return "tooLarge needs bytes and max"
+  if (v.chunk !== undefined) {
+    const c = v.chunk
+    if (!isObj(c) || !int(c.offset, 0, PREVIEW_BUNDLE_LIMITS.fileBytes) || typeof c.data !== "string" || typeof c.last !== "boolean") return "chunk needs offset, data and last"
+    if (c.data.length > Math.ceil(PREVIEW_BUNDLE_LIMITS.chunkBytes / 3) * 4) return "chunk is larger than chunkBytes"
+  }
+  if (!manifest) return undefined
+  if (typeof v.bundle !== "string" || !HEX64.test(v.bundle)) return "bundle must be a hex SHA-256"
+  if (!Array.isArray(v.files) || v.files.length < 1 || v.files.length > PREVIEW_BUNDLE_LIMITS.files) return `files must list 1–${PREVIEW_BUNDLE_LIMITS.files} files`
+  const paths = new Set<string>()
+  for (const f of v.files as unknown[]) {
+    if (!isObj(f) || !isBundlePath(f.path)) return "every file needs a relative bundle path"
+    if (paths.has(f.path)) return `path ${f.path} appears twice`
+    paths.add(f.path)
+    if (typeof f.mediaType !== "string" || !MEDIA_TYPES.has(f.mediaType)) return "mediaType is not allowed"
+    if (!int(f.bytes, 0, PREVIEW_BUNDLE_LIMITS.fileBytes)) return `bytes must be 0–${PREVIEW_BUNDLE_LIMITS.fileBytes}`
+    if (typeof f.sha256 !== "string" || !HEX64.test(f.sha256)) return "sha256 must be hex"
+    if (f.data !== undefined && typeof f.data !== "string") return "data must be base64"
+  }
+  if (typeof v.entry !== "string" || !paths.has(v.entry)) return "entry must be one of the files"
+  if (v.skipped !== undefined) {
+    if (!Array.isArray(v.skipped) || v.skipped.length > PREVIEW_BUNDLE_LIMITS.skipped) return `skipped lists at most ${PREVIEW_BUNDLE_LIMITS.skipped}`
+    for (const s of v.skipped as unknown[]) {
+      if (!isObj(s) || typeof s.path !== "string" || s.path.length > PREVIEW_BUNDLE_LIMITS.refMax || !(PREVIEW_SKIP_REASONS as readonly unknown[]).includes(s.reason)) return "a skipped file needs its path and a reason"
+    }
+  }
+  if (v.skippedMore !== undefined && !int(v.skippedMore, 1, Number.MAX_SAFE_INTEGER)) return "skippedMore must be a positive count"
+  return undefined
+}
+
+/**
+ * Whether a written target names a local HTML page: ends in .html/.htm (any case), no URL scheme but file:, no `~`
+ * (never expanded), at most pathMax characters, no NUL or line break.
+ */
+export function isHtmlTarget(target: string): boolean {
+  if (!isPreviewPath(target) || target.startsWith("~")) return false
+  if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(target) && !/^file:/i.test(target)) return false
+  return /\.html?$/i.test(target)
+}
+
+/**
+ * The local HTML pages a parsed text names, in order, without duplicates: code spans and link targets (same-site
+ * links' `href`, other links' raw `target`: `./page.html`) through paragraphs, headings, quotes, lists and tables; never in code blocks. The console shows Preview on
+ * exactly these, the spoke serves only these (it also leaves out indented code and reads a text's first 64 KiB).
+ */
+export function htmlTargets(blocks: readonly MdBlock[], out: string[] = []): string[] {
+  const add = (t: string) => {
+    if (isHtmlTarget(t) && !out.includes(t)) out.push(t)
+  }
+  const inline = (nodes: readonly Inline[]) => {
+    for (const node of nodes) {
+      if (node.type === "code") add(node.text)
+      else if (node.type === "link") {
+        add(node.href)
+        inline(node.children)
+      } else if (node.type === "label") {
+        add(node.target)
+        inline(node.children)
+      } else if ("children" in node) inline(node.children)
+    }
+  }
+  for (const block of blocks) {
+    if (block.type === "paragraph" || block.type === "heading") inline(block.children)
+    else if (block.type === "quote") htmlTargets(block.blocks, out)
+    else if (block.type === "list") for (const item of block.items) htmlTargets(item.blocks, out)
+    else if (block.type === "table") for (const row of [block.head, ...block.rows]) for (const cell of row) inline(cell)
+  }
+  return out
+}

package/packages/protocol/src/voice-recording.ts

@@ -7,6 +7,13 @@ export const RECORDING_HEADER = "x-hub-recording"            // on /api/transcri
 export const RECORDING_SEGMENT_HEADER = "x-hub-segment"      // on /api/transcribe: the segment number
 export const RECORDING_REF_HEADER = "x-hub-tts-ref"          // on /api/speak: "<messageID>:<ordinal>:<seq>:<i>"
 export const RECORDING_AUDIO_RESULT_HEADER = "x-hub-recording-audio" // transcribe answer: RecordingAudioResult
+/**
+ * Console kinds and values added after version 1, listed in the start answer (`features`): a console sends them only
+ * to a hub that lists them (an older hub refuses a whole batch with an unknown kind or value).
+ *   "turn.predict": the turn.predict kind and utterance.sent reasons "smart" / "smart-fallback" (Smart Turn).
+ */
+export const RECORDING_FEATURES = ["turn.predict"] as const
+export type RecordingFeature = (typeof RECORDING_FEATURES)[number]
 
 export const RECORDING_LIMITS = {
   retentionMs: 7 * 24 * 3_600_000,
@@ -82,6 +89,7 @@ export type ConsoleEventKind =
   | "heard" | "say.received" | "tts.sentence.queued" | "tts.request" | "tts.first.byte" | "tts.sentence.played"
   | "tts.sentence.ended" | "barge.in" | "cue.played" | "mic" | "control" | "turn.timing" | "decision.voice"
   | "clock.sync" | "error"
+  | "turn.predict" // feature "turn.predict"
 export type HubEventKind =
   | "recording.started" | "recording.ended" | "conversation" | "stt.request" | "stt.result" | "tts.synth"
   | "utterance.received" | "utterance.delivered" | "turn.started" | "first.token" | "say.sent" | "reply.full"

package/packages/runtime-openshell/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-runtime-openshell",
-  "version": "0.8.6",
+  "version": "0.9.0",
   "private": true,
   "description": "The `openshell` runtime of `hub node`: launches in NVIDIA OpenShell sandboxes, driven through the openshell CLI (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/runtime-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-runtime-sdk",
-  "version": "0.8.6",
+  "version": "0.9.0",
   "private": true,
   "description": "The Runtime interface `hub node` runtimes implement (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-sdk",
-  "version": "0.8.6",
+  "version": "0.9.0",
   "private": true,
   "description": "Typed client for the hub's /api/agent (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",