@unifedev/thread-pages 0.3.2 → 1.1.0

package/src/pages/inline.ts

@@ -0,0 +1,277 @@
+import { defaultTreeAdapter, parse as parseHtml, serialize as serializeHtml, type DefaultTreeAdapterTypes } from "parse5";
+import { LIMITS } from "../domain/limits.ts";
+import { isSafeRelativePath } from "./layout.ts";
+
+/**
+ * Resolving a page's own files into its entry document. spec R1.2, R1.3, R4.25–R4.27
+ *
+ * A page frame is sandboxed, so it has an opaque origin, so every subresource
+ * it requests is cross-site and carries no host credential. A bb served over
+ * loopback needs none and the file arrives; a bb reached through an
+ * authenticated origin refuses it. The page renders, its own stylesheet and
+ * data do not, nothing errors, and the author cannot see any of this from the
+ * machine that wrote the page.
+ *
+ * So the entry document — the one artifact whose request is issued by trusted
+ * chrome and therefore always authorised — carries the page's own files with
+ * it. Each relative reference is rewritten to a `data:` URL, which the
+ * document's CSP already permits. Rewriting the attribute rather than moving
+ * the bytes into the element keeps every other attribute meaningful (`defer`,
+ * `type="module"`, `media`, `loading`) and avoids the escaping traps that
+ * inlining raw text into `<script>` and `<style>` carries.
+ *
+ * THIS IS A WORKAROUND AND IT SHOULD BE DELETED. It exists only because the
+ * host cannot authorise a sandboxed document's own subresource requests. Once
+ * it can — see docs/B1-OWN-FILES.md — a page's files should be served as
+ * files again, and this module and its wiring should go.
+ */
+
+type HtmlElement = DefaultTreeAdapterTypes.Element;
+type HtmlNode = DefaultTreeAdapterTypes.ChildNode;
+
+export interface OwnFile {
+  readonly bytes: Uint8Array;
+  readonly mimeType?: string | undefined;
+}
+
+export type OwnFileReader = (relativePath: string) => Promise<OwnFile | null>;
+
+export interface ResolvedFile {
+  readonly path: string;
+  readonly bytes: number;
+}
+
+export interface SkippedFile {
+  readonly path: string;
+  readonly reason: "missing" | "too-large" | "budget" | "unsafe-path";
+}
+
+export interface ResolveOutcome {
+  readonly html: string;
+  readonly resolved: readonly ResolvedFile[];
+  readonly skipped: readonly SkippedFile[];
+}
+
+/** Attributes that may name one of the page's own files, per element. */
+const CARRIERS: ReadonlyArray<{ tag: string; attr: string; test?: (element: HtmlElement) => boolean }> = [
+  { tag: "link", attr: "href", test: (element) => relOf(element).some((rel) => rel === "stylesheet" || rel === "icon" || rel === "shortcut" || rel === "apple-touch-icon" || rel === "preload") },
+  { tag: "script", attr: "src" },
+  { tag: "img", attr: "src" },
+  { tag: "source", attr: "src" },
+  { tag: "audio", attr: "src" },
+  { tag: "video", attr: "src" },
+  { tag: "video", attr: "poster" },
+  { tag: "track", attr: "src" },
+];
+
+function relOf(element: HtmlElement): string[] {
+  const rel = attributeOf(element, "rel") ?? "";
+  return rel.toLowerCase().split(/\s+/).filter(Boolean);
+}
+
+function attributeOf(element: HtmlElement, name: string): string | null {
+  return element.attrs.find((attr) => attr.name === name)?.value ?? null;
+}
+
+function setAttribute(element: HtmlElement, name: string, value: string): void {
+  const existing = element.attrs.find((attr) => attr.name === name);
+  if (existing) existing.value = value;
+  else element.attrs.push({ name, value });
+}
+
+/**
+ * True for a reference that names a file inside this page's own root. Anything
+ * absolute, protocol-relative, already a URL, or a bare fragment belongs to
+ * somebody else and is left exactly as the author wrote it.
+ */
+export function isOwnFileReference(value: string): boolean {
+  const trimmed = value.trim();
+  if (trimmed.length === 0) return false;
+  if (trimmed.startsWith("#") || trimmed.startsWith("/") || trimmed.startsWith("//")) return false;
+  if (/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(trimmed)) return false;
+  return true;
+}
+
+/** The reference's path, with any query or fragment removed and percent-escapes resolved. */
+function pathOf(reference: string): string | null {
+  const withoutHash = reference.trim().split("#")[0] ?? "";
+  const withoutQuery = withoutHash.split("?")[0] ?? "";
+  if (withoutQuery.length === 0) return null;
+  try {
+    return decodeURIComponent(withoutQuery);
+  } catch {
+    return withoutQuery;
+  }
+}
+
+function mimeFor(path: string, declared: string | undefined): string {
+  if (declared && declared.length > 0) return declared;
+  const extension = path.slice(path.lastIndexOf(".") + 1).toLowerCase();
+  return EXTENSION_TYPES[extension] ?? "application/octet-stream";
+}
+
+const EXTENSION_TYPES: Readonly<Record<string, string>> = Object.freeze({
+  css: "text/css",
+  js: "text/javascript",
+  mjs: "text/javascript",
+  json: "application/json",
+  svg: "image/svg+xml",
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  avif: "image/avif",
+  ico: "image/x-icon",
+  woff: "font/woff",
+  woff2: "font/woff2",
+  ttf: "font/ttf",
+  otf: "font/otf",
+  mp4: "video/mp4",
+  webm: "video/webm",
+  mp3: "audio/mpeg",
+  wav: "audio/wav",
+  vtt: "text/vtt",
+});
+
+function dataUrl(bytes: Uint8Array, mimeType: string): string {
+  return `data:${mimeType};base64,${Buffer.from(bytes).toString("base64")}`;
+}
+
+/** `url(...)` references inside an inlined stylesheet, which would otherwise resolve nowhere. */
+const CSS_URL = /url\(\s*(['"]?)([^'")]+)\1\s*\)/g;
+
+/**
+ * Rewrites every reference to one of the page's own files into a `data:` URL,
+ * one level deep inside stylesheets as well. Anything that cannot be resolved
+ * is left untouched and reported, so the page degrades to exactly the
+ * behaviour it has without this pass rather than to a broken document.
+ */
+export async function resolveOwnFiles(html: string, read: OwnFileReader): Promise<ResolveOutcome> {
+  const document = parseHtml(html);
+  const resolved: ResolvedFile[] = [];
+  const skipped: SkippedFile[] = [];
+  const seen = new Map<string, string | null>();
+  let budget = LIMITS.inlineTotalBytes;
+
+  async function urlFor(path: string, depth: number): Promise<string | null> {
+    const memo = seen.get(path);
+    if (memo !== undefined) return memo;
+    const answer = await load(path, depth);
+    seen.set(path, answer);
+    return answer;
+  }
+
+  async function load(path: string, depth: number): Promise<string | null> {
+    if (!isSafeRelativePath(path)) {
+      skipped.push({ path, reason: "unsafe-path" });
+      return null;
+    }
+    const file = await read(path).catch(() => null);
+    if (!file) {
+      skipped.push({ path, reason: "missing" });
+      return null;
+    }
+    if (file.bytes.byteLength > LIMITS.inlineFileBytes) {
+      skipped.push({ path, reason: "too-large" });
+      return null;
+    }
+    if (file.bytes.byteLength > budget) {
+      skipped.push({ path, reason: "budget" });
+      return null;
+    }
+    budget -= file.bytes.byteLength;
+    const mimeType = mimeFor(path, file.mimeType);
+    const bytes = mimeType === "text/css" && depth < LIMITS.inlineCssDepth ? Buffer.from(await resolveCss(Buffer.from(file.bytes).toString("utf8"), path, depth), "utf8") : file.bytes;
+    resolved.push({ path, bytes: file.bytes.byteLength });
+    return dataUrl(bytes, mimeType);
+  }
+
+  /** A stylesheet becomes a `data:` URL, so its own relative `url()`s must be resolved first. */
+  async function resolveCss(css: string, from: string, depth: number): Promise<string> {
+    const base = from.includes("/") ? from.slice(0, from.lastIndexOf("/") + 1) : "";
+    const replacements = new Map<string, string>();
+    for (const match of css.matchAll(CSS_URL)) {
+      const reference = match[2] ?? "";
+      if (!isOwnFileReference(reference) || replacements.has(reference)) continue;
+      const path = pathOf(reference);
+      if (!path) continue;
+      const url = await urlFor(normalise(base + path), depth + 1);
+      if (url) replacements.set(reference, url);
+    }
+    if (replacements.size === 0) return css;
+    return css.replace(CSS_URL, (whole, quote: string, reference: string) => {
+      const url = replacements.get(reference);
+      return url ? `url(${quote}${url}${quote})` : whole;
+    });
+  }
+
+  const elements: HtmlElement[] = [];
+  const walk = (node: HtmlNode | DefaultTreeAdapterTypes.Document): void => {
+    if (defaultTreeAdapter.isElementNode(node as HtmlNode)) elements.push(node as HtmlElement);
+    for (const child of (node as { childNodes?: HtmlNode[] }).childNodes ?? []) walk(child);
+  };
+  walk(document);
+
+  let changed = false;
+  for (const element of elements) {
+    for (const carrier of CARRIERS) {
+      if (element.tagName !== carrier.tag) continue;
+      if (carrier.test && !carrier.test(element)) continue;
+      const reference = attributeOf(element, carrier.attr);
+      if (reference === null || !isOwnFileReference(reference)) continue;
+      const path = pathOf(reference);
+      if (!path) continue;
+      const url = await urlFor(normalise(path), 0);
+      if (!url) continue;
+      setAttribute(element, carrier.attr, url);
+      changed = true;
+    }
+    // srcset carries several candidates; all or nothing keeps the parsing simple.
+    if (element.tagName === "img" || element.tagName === "source") {
+      const srcset = attributeOf(element, "srcset");
+      if (srcset !== null) {
+        const rewritten = await resolveSrcset(srcset, urlFor);
+        if (rewritten !== null) {
+          setAttribute(element, "srcset", rewritten);
+          changed = true;
+        }
+      }
+    }
+  }
+
+  return { html: changed ? serializeHtml(document) : html, resolved, skipped };
+}
+
+async function resolveSrcset(srcset: string, urlFor: (path: string, depth: number) => Promise<string | null>): Promise<string | null> {
+  const candidates = srcset.split(",").map((entry) => entry.trim()).filter(Boolean);
+  const rewritten: string[] = [];
+  let changed = false;
+  for (const candidate of candidates) {
+    const [reference, ...descriptor] = candidate.split(/\s+/);
+    if (!reference || !isOwnFileReference(reference)) {
+      rewritten.push(candidate);
+      continue;
+    }
+    const path = pathOf(reference);
+    const url = path ? await urlFor(normalise(path), 0) : null;
+    if (!url) {
+      rewritten.push(candidate);
+      continue;
+    }
+    changed = true;
+    rewritten.push([url, ...descriptor].join(" "));
+  }
+  return changed ? rewritten.join(", ") : null;
+}
+
+/** Collapses `a/./b` and `a/b/../c`; a path that climbs out fails `isSafeRelativePath` later. */
+function normalise(path: string): string {
+  const out: string[] = [];
+  for (const segment of path.split("/")) {
+    if (segment === "" || segment === ".") continue;
+    if (segment === ".." && out.length > 0 && out[out.length - 1] !== "..") out.pop();
+    else out.push(segment);
+  }
+  return out.join("/");
+}

package/src/pages/layout.ts

@@ -0,0 +1,65 @@
+/**
+ * Where a page lives. spec 01 §Storage, RW-3
+ *
+ * The page root is the session's storage directory itself. The entry document
+ * is `index.html`; reader uploads land in `uploads/` under host-generated
+ * names. Everything else in the root is the page's own site.
+ */
+export const ENTRY_FILE = "index.html";
+export const UPLOAD_DIR = "uploads";
+/** The prototype's entry file, recognised only to tell an agent about it. */
+export const LEGACY_ENTRY_FILE = "thread-page.html";
+
+const UPLOAD_NAME = /^[0-9]{8}-[0-9]{6}-[a-f0-9]{6}-[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/;
+
+export function joinPath(root: string, ...segments: string[]): string {
+  const base = root.replace(/[\\/]+$/, "");
+  return [base, ...segments].join("/");
+}
+
+export function entryPath(root: string): string {
+  return joinPath(root, ENTRY_FILE);
+}
+
+export function legacyEntryPath(root: string): string {
+  return joinPath(root, LEGACY_ENTRY_FILE);
+}
+
+export function uploadPath(root: string, name: string): string {
+  if (!isSafeUploadName(name)) throw new Error("Unsafe upload name");
+  return joinPath(root, UPLOAD_DIR, name);
+}
+
+/** The reader's filename reduced to a safe suffix; the host chooses the rest. spec R4.21 */
+export function sanitizeUploadSuffix(raw: string): string {
+  let decoded = raw;
+  try {
+    decoded = decodeURIComponent(raw);
+  } catch {
+    decoded = raw;
+  }
+  const base = decoded.split(/[\\/]/).pop() ?? "";
+  const cleaned = base.replace(/[^A-Za-z0-9._-]/g, "_").replace(/^[._-]+/, "");
+  return cleaned.slice(0, 80) || "upload";
+}
+
+/** `YYYYMMDD-HHMMSS-<6 hex>-<suffix>`; never taken from the reader. spec R4.21 */
+export function uploadFileName(originalName: string, now: number, randomHex: string): string {
+  const stamp = new Date(now).toISOString().replace(/[-:]/g, "").replace(/\..+$/, "").replace("T", "-");
+  const name = `${stamp}-${randomHex.slice(0, 6)}-${sanitizeUploadSuffix(originalName)}`;
+  if (!isSafeUploadName(name)) throw new Error("Generated upload name is invalid");
+  return name;
+}
+
+export function isSafeUploadName(name: string): boolean {
+  return UPLOAD_NAME.test(name) && !name.includes("..");
+}
+
+/**
+ * A relative path inside the page root: no absolute paths, no `.`/`..`/empty
+ * segments, no backslashes, no NUL. spec R1.4
+ */
+export function isSafeRelativePath(path: string): boolean {
+  if (path.length === 0 || path.length > 1024 || path.includes("\0") || path.includes("\\") || path.startsWith("/")) return false;
+  return path.split("/").every((segment) => segment.length > 0 && segment !== "." && segment !== "..");
+}

package/src/pages/page-store.ts

@@ -0,0 +1,170 @@
+import { PageError, PUBLIC_MESSAGES, errorText } from "../domain/errors.ts";
+import { isRevision } from "../domain/ids.ts";
+import { LIMITS } from "../domain/limits.ts";
+import { revisionOf } from "../domain/revision.ts";
+import type { SessionHost } from "../host/contract.ts";
+import type { ResolveOutcome } from "./inline.ts";
+import { ENTRY_FILE } from "./layout.ts";
+
+/**
+ * Loads a page's entry document, bounds it, computes its revision, and keeps
+ * a last-known-good copy so the page still opens read-only when its source
+ * host is unreachable. spec R1.7, R2.11, R2.27–R2.30
+ */
+export interface LoadedPage {
+  readonly html: string;
+  readonly revision: string;
+  readonly updatedAtMs: number;
+  /** True when served from the offline copy. */
+  readonly stale: boolean;
+  /** Own files carried into the document, and those that could not be. */
+  readonly site: { readonly resolved: number; readonly skipped: readonly { path: string; reason: string }[] };
+}
+
+interface CachedPage {
+  readonly html: string;
+  readonly revision: string;
+  readonly updatedAtMs: number;
+}
+
+/**
+ * Resolves a page's own files into its entry document so it renders on an
+ * origin that will not authorise the sandbox's subresource requests.
+ * Temporary; see pages/inline.ts. spec R1.2, R4.25-R4.27
+ */
+export type PageResolver = (session: string, html: string) => Promise<ResolveOutcome>;
+
+export interface PageStore {
+  load(session: string): Promise<LoadedPage>;
+  /** Records a document the plugin just wrote, so the next load is warm. */
+  remember(session: string, html: string): Promise<CachedPage>;
+  /** The revision last seen for a session, without touching the host. */
+  knownRevision(session: string): string | null;
+}
+
+const KV_PREFIX = "cache:";
+
+export function createPageStore(host: SessionHost, resolve?: PageResolver): PageStore {
+  const memory = new Map<string, CachedPage>();
+  let memoryBytes = 0;
+
+  function cost(page: CachedPage): number {
+    return Buffer.byteLength(page.html, "utf8") + 128;
+  }
+
+  function retain(session: string, page: CachedPage): void {
+    const previous = memory.get(session);
+    if (previous) {
+      memoryBytes -= cost(previous);
+      memory.delete(session);
+    }
+    memory.set(session, page);
+    memoryBytes += cost(page);
+    while (memory.size > LIMITS.offlineCacheEntries || memoryBytes > LIMITS.offlineCacheBytes) {
+      const oldest = memory.keys().next().value;
+      if (oldest === undefined) break;
+      const evicted = memory.get(oldest);
+      memory.delete(oldest);
+      if (evicted) memoryBytes -= cost(evicted);
+    }
+  }
+
+  async function persist(session: string, page: CachedPage, previousRevision: string | undefined): Promise<void> {
+    if (previousRevision === page.revision) return;
+    const key = KV_PREFIX + session;
+    const bytes = Buffer.byteLength(page.html, "utf8");
+    if (bytes > LIMITS.offlineCopyBytes) {
+      // Silently dropping this is how a page stops opening offline with no
+      // author ever learning why. Carrying a page's own files into the
+      // document makes it much easier to cross. spec R2.27-R2.31
+      host.log.warn(
+        `offline copy: ${session} is ${Math.round(bytes / 1024)} KiB, over the ${LIMITS.offlineCopyBytes / 1024} KiB limit — ` +
+          "the page will not open while its host is unreachable",
+      );
+      await host.kv.delete(key).catch((error: unknown) => host.log.warn(`offline copy: could not clear ${session}: ${errorText(error)}`));
+      return;
+    }
+    await host.kv.set(key, { html: page.html, revision: page.revision, updatedAtMs: page.updatedAtMs }).catch((error: unknown) => {
+      host.log.warn(`offline copy: could not store ${session}: ${errorText(error)}`);
+    });
+  }
+
+  async function cached(session: string): Promise<CachedPage | null> {
+    const resident = memory.get(session);
+    if (resident) return resident;
+    try {
+      const stored = await host.kv.get(KV_PREFIX + session);
+      if (!isCachedPage(stored)) return null;
+      retain(session, stored);
+      return stored;
+    } catch (error) {
+      host.log.warn(`offline copy: could not read ${session}: ${errorText(error)}`);
+      return null;
+    }
+  }
+
+  async function remember(session: string, html: string, updatedAtMs = Date.now()): Promise<CachedPage> {
+    const page: CachedPage = { html, revision: revisionOf(html), updatedAtMs };
+    const previous = memory.get(session)?.revision;
+    retain(session, page);
+    await persist(session, page, previous);
+    return page;
+  }
+
+  return {
+    async load(session) {
+      let content;
+      try {
+        const location = await host.sessions.storage(session);
+        content = await host.files.read(location, ENTRY_FILE);
+      } catch (error) {
+        const fallback = await cached(session);
+        if (fallback) return { ...fallback, stale: true, site: { resolved: 0, skipped: [] } };
+        throw PageError.is(error) ? error : new PageError("unavailable", PUBLIC_MESSAGES.unavailable, { cause: error });
+      }
+      if (!content) throw new PageError("no_page", PUBLIC_MESSAGES.noPage);
+      if (content.bytes.byteLength > LIMITS.entryDocumentBytes) {
+        throw new PageError("page_too_large", PUBLIC_MESSAGES.pageTooLarge);
+      }
+      const authored = Buffer.from(content.bytes).toString("utf8");
+      let html = authored;
+      let site: LoadedPage["site"] = { resolved: 0, skipped: [] };
+      if (resolve) {
+        try {
+          const outcome = await resolve(session, authored);
+          html = outcome.html;
+          site = { resolved: outcome.resolved.length, skipped: outcome.skipped };
+          for (const file of outcome.skipped) {
+            host.log.warn(`page ${session}: ${file.path} is referenced but was not carried into the document (${file.reason})`);
+          }
+        } catch (error) {
+          // A page that renders without its own files beats a page that does
+          // not render. Serve what the agent wrote.
+          host.log.warn(`page ${session}: could not resolve its own files: ${errorText(error)}`);
+        }
+      }
+      const page: CachedPage = { html, revision: revisionOf(html), updatedAtMs: content.modifiedAtMs ?? Date.now() };
+      const previous = memory.get(session)?.revision;
+      retain(session, page);
+      await persist(session, page, previous);
+      return { ...page, stale: false, site };
+    },
+    remember,
+    knownRevision(session) {
+      return memory.get(session)?.revision ?? null;
+    },
+  };
+}
+
+function isCachedPage(value: unknown): value is CachedPage {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const entry = value as Record<string, unknown>;
+  return (
+    typeof entry.html === "string" &&
+    Buffer.byteLength(entry.html, "utf8") <= LIMITS.offlineCopyBytes &&
+    isRevision(entry.revision) &&
+    revisionOf(entry.html) === entry.revision &&
+    typeof entry.updatedAtMs === "number" &&
+    Number.isFinite(entry.updatedAtMs)
+  );
+}

package/src/pages/site.ts

@@ -0,0 +1,36 @@
+/**
+ * How a page's site reaches the reader. spec R1.2, R1.3; rewrite RW-1
+ *
+ * The document is always served by this plugin (it needs the kernel). Where
+ * its files come from depends on what the host's router can do:
+ *
+ * - `core-storage`: the host already serves the session's storage as a site
+ *   at a stable path; the document gets one same-origin `<base>` so relative
+ *   references resolve there. This is what bb 0.42.1 allows.
+ * - `plugin-prefix`: the plugin serves `/page/<id>/…` itself; the document
+ *   URL is path-shaped and no base is needed. Available once the host's
+ *   plugin router matches prefixes.
+ */
+export interface SiteStrategy {
+  readonly name: "core-storage" | "plugin-prefix";
+  /** Origin-relative URL the shell loads into the iframe. */
+  documentUrl(session: string): string;
+  /** Same-origin `<base href>` to inject, or null when the document URL is path-shaped. */
+  baseHref(session: string): string | null;
+}
+
+export function createCoreStorageSite(routeBase: string, storageFilesBase: (session: string) => string): SiteStrategy {
+  return {
+    name: "core-storage",
+    documentUrl: (session) => `${routeBase}/document?session=${encodeURIComponent(session)}`,
+    baseHref: (session) => storageFilesBase(session),
+  };
+}
+
+export function createPluginPrefixSite(routeBase: string): SiteStrategy {
+  return {
+    name: "plugin-prefix",
+    documentUrl: (session) => `${routeBase}/page/${encodeURIComponent(session)}/`,
+    baseHref: () => null,
+  };
+}

package/src/plugin.ts

@@ -0,0 +1,81 @@
+import type { BbPluginApi } from "@get-bb/plugin-sdk";
+import { registerCli } from "./agent/cli.ts";
+import { buildGuide } from "./agent/guide.ts";
+import { createBbHost } from "./bb/bb-host.ts";
+import { defineSettings } from "./config/settings.ts";
+import { capabilityRegistry } from "./domain/capabilities/index.ts";
+import { createRateLimiter } from "./domain/rate-limit.ts";
+import { createOutcomeMemory } from "./domain/submissions/idempotency.ts";
+import type { SessionHost } from "./host/contract.ts";
+import { resolveOwnFiles } from "./pages/inline.ts";
+import { createPageStore } from "./pages/page-store.ts";
+import { createCoreStorageSite, type SiteStrategy } from "./pages/site.ts";
+import { createSelectionStore } from "./serving/bridge/selection-store.ts";
+import type { ServingContext } from "./serving/context.ts";
+import { registerRoutes } from "./serving/routes.ts";
+import { loadSigningKey } from "./serving/signing-key.ts";
+
+/**
+ * The composition root: the only file that knows every package. Builds the
+ * host adapter, the stores and the serving context, then registers routes,
+ * the CLI and the agent-instruction hook.
+ */
+export interface PluginOptions {
+  /** Override the host (tests). */
+  host?: SessionHost;
+  /** Override the site strategy (tests, or a host with prefix routes). */
+  site?: (routeBase: string) => SiteStrategy;
+  now?: () => number;
+}
+
+export async function createPlugin(bb: BbPluginApi, options: PluginOptions = {}): Promise<ServingContext> {
+  const settings = await defineSettings(bb);
+  const host = options.host ?? createBbHost(bb);
+  const signingKey = await loadSigningKey(host);
+  const routeBase = `/api/v1/plugins/${bb.pluginId}/http`;
+  const site = options.site
+    ? options.site(routeBase)
+    : createCoreStorageSite(routeBase, (session) => `/api/v1/threads/${encodeURIComponent(session)}/thread-storage/files/`);
+
+  const serving: ServingContext = {
+    host,
+    // Strategy A cannot serve a sandboxed document's own files on an
+    // authenticated origin, so the document carries them. Delete this
+    // argument, and pages/inline.ts, once the host can authorise them.
+    pages: createPageStore(host, async (session, html) => {
+      const location = await host.sessions.storage(session);
+      return resolveOwnFiles(html, async (path) => {
+        const file = await host.files.read(location, path);
+        return file ? { bytes: file.bytes } : null;
+      });
+    }),
+    settings,
+    signingKey,
+    site,
+    routeBase,
+    registry: capabilityRegistry,
+    rate: createRateLimiter(),
+    submissions: createOutcomeMemory(),
+    replies: createOutcomeMemory(),
+    selections: createSelectionStore(),
+    hostSessionUrl: (session) => `/threads/${encodeURIComponent(session)}`,
+    now: options.now ?? (() => Date.now()),
+  };
+
+  const effectiveInstruction = (): string | null => {
+    const current = settings.current();
+    return current.agentInstructions && current.agentInstructionText.trim() ? current.agentInstructionText : null;
+  };
+
+  // The standing instruction: only eligible sessions, only when enabled.
+  // Visibility is not known here, so `init` rechecks eligibility at call time. spec R6.14
+  bb.agents.configure((context) => {
+    const instruction = effectiveInstruction();
+    const root = context.thread.parentThreadId === null && context.thread.sourceThreadId === null && context.origin.kind === null;
+    return instruction && root ? { tools: [], skills: [], instructions: instruction } : { tools: [], skills: [] };
+  });
+
+  registerRoutes(bb, serving);
+  registerCli(bb, { serving, guide: buildGuide(capabilityRegistry, site), effectiveInstruction });
+  return serving;
+}

package/src/runtime/kernel/anchors.ts

@@ -0,0 +1,45 @@
+/**
+ * Authored links work. spec R4.15
+ *
+ * The sandbox has no top-level navigation, so an `<a href>` to another site
+ * would silently do nothing (or replace the page inside the frame). The
+ * kernel routes http(s) destinations through `navigation.openExternal`,
+ * leaves same-document fragments and the page's own files to the browser,
+ * and swallows schemes the sandbox cannot honour.
+ */
+export type AnchorDecision = { kind: "default" } | { kind: "external"; url: string; label: string } | { kind: "block" };
+
+export function decideAnchor(anchor: HTMLAnchorElement, documentUrl: string, siteBase: string | null): AnchorDecision {
+  const raw = anchor.getAttribute("href");
+  if (raw === null) return { kind: "default" };
+  if (raw.startsWith("#")) return { kind: "default" };
+  let target: URL;
+  try {
+    target = new URL(raw, siteBase ?? documentUrl);
+  } catch {
+    return { kind: "block" };
+  }
+  if (target.protocol !== "http:" && target.protocol !== "https:") return { kind: "block" };
+  if (siteBase && target.href.startsWith(siteBase)) return { kind: "default" };
+  if (anchor.hasAttribute("download")) return { kind: "default" };
+  return { kind: "external", url: target.href, label: (anchor.textContent || "").replace(/\s+/g, " ").trim().slice(0, 160) };
+}
+
+export function installAnchorInterception(doc: Document, open: (url: string, label: string) => void): void {
+  doc.addEventListener(
+    "click",
+    (event) => {
+      if (event.defaultPrevented || event.button !== 0) return;
+      const target = event.target as Element | null;
+      const anchor = target?.closest?.("a[href]") as HTMLAnchorElement | null;
+      if (!anchor) return;
+      const base = doc.querySelector("base")?.getAttribute("href") ?? null;
+      const siteBase = base ? new URL(base, doc.baseURI).href : null;
+      const decision = decideAnchor(anchor, doc.baseURI, siteBase);
+      if (decision.kind === "default") return;
+      event.preventDefault();
+      if (decision.kind === "external") open(decision.url, decision.label);
+    },
+    true,
+  );
+}