@unifedev/thread-pages 0.3.2 → 1.0.3

package/src/runtime/shell/navigate.ts

@@ -0,0 +1,64 @@
+/**
+ * Navigation belongs to the trusted shell. Destinations arrive from the host,
+ * already validated; the shell never builds one from page-supplied text.
+ * spec R5.29–R5.34
+ */
+export interface Navigator {
+  /** Same-origin destinations navigate the reader's view in place. */
+  inPlace(url: string): void;
+  /** Claims a window during a user gesture so a later navigation is not a blocked popup. */
+  reserveWindow(): void;
+  /** Sends the reserved window (or, failing that, this view) to an external URL. */
+  external(url: string): void;
+  /** Releases a reserved window that will not be used. */
+  release(): void;
+}
+
+export function createNavigator(win: Window): Navigator {
+  let reserved: Window | null = null;
+  return {
+    inPlace(url) {
+      win.location.assign(url);
+    },
+    reserveWindow() {
+      try {
+        reserved = win.open("", "_blank");
+        if (reserved) {
+          try {
+            reserved.opener = null;
+          } catch {
+            // Some browsers refuse; the navigation below still uses noreferrer semantics.
+          }
+        }
+      } catch {
+        reserved = null;
+      }
+    },
+    external(url) {
+      const target = reserved;
+      reserved = null;
+      if (target && !target.closed) {
+        try {
+          target.location.href = url;
+          return;
+        } catch {
+          try {
+            target.close();
+          } catch {
+            // ignore
+          }
+        }
+      }
+      win.location.assign(url);
+    },
+    release() {
+      const target = reserved;
+      reserved = null;
+      try {
+        target?.close();
+      } catch {
+        // ignore
+      }
+    },
+  };
+}

package/src/runtime/shell/poll.ts

@@ -0,0 +1,125 @@
+import type { ShellConfig } from "../shared/protocol.ts";
+
+/**
+ * The revision poll: a conditional GET of the document every few seconds
+ * while the tab is visible. It carries the working indicator and the
+ * source state, so no second channel exists. spec R2.17–R2.26
+ */
+export interface PollView {
+  setStatus(text: string, warn: boolean): void;
+  setWorking(working: boolean): void;
+  showReload(visible: boolean): void;
+  onStaleChanged(stale: boolean): void;
+  reloadView(): void;
+}
+
+export interface Poller {
+  start(): void;
+  setDirty(dirty: boolean): void;
+  /** For tests: run one poll now. */
+  pollNow(): Promise<void>;
+  isStopped(): boolean;
+}
+
+export function createPoller(win: Window, config: ShellConfig, view: PollView, fetchImpl: typeof fetch = win.fetch.bind(win)): Poller {
+  let etag = `"${config.pageRevision}"`;
+  let dirty = false;
+  let stopped = false;
+  let polling = false;
+  let lastStale = config.stale;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let controller: AbortController | null = null;
+
+  function schedule(delay: number): void {
+    if (timer !== null) clearTimeout(timer);
+    timer = null;
+    if (stopped || win.document.visibilityState !== "visible") return;
+    timer = setTimeout(() => {
+      timer = null;
+      void poll();
+    }, delay);
+  }
+
+  function pause(): void {
+    if (timer !== null) clearTimeout(timer);
+    timer = null;
+    controller?.abort();
+    controller = null;
+  }
+
+  function newVersion(): void {
+    if (dirty) {
+      view.setStatus("Page changed — reload when ready", true);
+      view.showReload(true);
+    } else {
+      view.reloadView();
+    }
+  }
+
+  async function poll(): Promise<void> {
+    if (stopped || polling || win.document.visibilityState !== "visible") return;
+    if (Date.now() >= config.expiresAt - 30_000) {
+      stopped = true;
+      if (dirty) {
+        view.setStatus("Session expiring — reload when ready", true);
+        view.showReload(true);
+      } else {
+        view.reloadView();
+      }
+      return;
+    }
+    polling = true;
+    controller = new AbortController();
+    try {
+      const response = await fetchImpl(config.documentUrl, {
+        method: "GET",
+        credentials: "same-origin",
+        cache: "no-store",
+        headers: { "if-none-match": etag },
+        signal: controller.signal,
+      });
+      if (response.status === 401 || response.status === 403) {
+        stopped = true;
+        view.setStatus("Session expired — reload this page", true);
+        view.showReload(true);
+        return;
+      }
+      if (!response.ok && response.status !== 304) {
+        view.setStatus("Page unavailable", true);
+        return;
+      }
+      const stale = response.headers.get("x-thread-page-stale") === "true";
+      view.setWorking(response.headers.get("x-thread-page-activity") === "working");
+      if (stale !== lastStale) {
+        lastStale = stale;
+        view.onStaleChanged(stale);
+      }
+      view.setStatus(stale ? "Offline copy — read-only" : "", stale);
+      const next = response.headers.get("etag");
+      if (next && next !== etag) {
+        etag = next;
+        newVersion();
+      }
+    } catch (error) {
+      if (!(error instanceof DOMException && error.name === "AbortError")) view.setStatus("Cannot check for updates", true);
+    } finally {
+      controller = null;
+      polling = false;
+      schedule(config.pollMs);
+    }
+  }
+
+  win.document.addEventListener("visibilitychange", () => {
+    if (win.document.visibilityState === "visible") schedule(0);
+    else pause();
+  });
+
+  return {
+    start: () => schedule(config.pollMs),
+    setDirty: (next) => {
+      dirty = next;
+    },
+    pollNow: () => poll(),
+    isStopped: () => stopped,
+  };
+}

package/src/runtime/shell/relay.ts

@@ -0,0 +1,185 @@
+import { isBridgeRequest, isBridgeResponse, isRecord, makeFailure, type BridgeRequestMessage, type ShellConfig, type ShellMessage, type SubmitFile } from "../shared/protocol.ts";
+import type { Confirmer } from "./confirm.ts";
+import type { Navigator } from "./navigate.ts";
+
+/**
+ * The shell's side of the port: it validates every message from the frame,
+ * carries bridge calls and submissions to the host with the action token,
+ * shows host-authored confirmations, and executes host-validated navigation.
+ * spec R3.5–R3.7, R3.17
+ */
+export interface RelayDeps {
+  config: ShellConfig;
+  confirmer: Confirmer;
+  navigator: Navigator;
+  onDirty(dirty: boolean): void;
+  fetchImpl?: typeof fetch;
+}
+
+export interface Relay {
+  handle(port: MessagePort, data: unknown): void;
+}
+
+type Directive = { kind: "page" | "host" | "external"; url: string };
+
+export function createRelay(deps: RelayDeps): Relay {
+  const { config, confirmer, navigator } = deps;
+  const fetchImpl = deps.fetchImpl ?? fetch;
+
+  function reply(port: MessagePort, message: ShellMessage): void {
+    port.postMessage(message);
+  }
+
+  async function postBridge(body: unknown): Promise<unknown> {
+    const response = await fetchImpl(config.bridgeUrl, {
+      method: "POST",
+      credentials: "same-origin",
+      cache: "no-store",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    return response.json().catch(() => null);
+  }
+
+  function directiveOf(value: unknown): Directive | null {
+    if (!isRecord(value)) return null;
+    if ((value.kind !== "page" && value.kind !== "host" && value.kind !== "external") || typeof value.url !== "string") return null;
+    if (value.kind === "external" && !/^https?:\/\//i.test(value.url)) return null;
+    if (value.kind !== "external" && !value.url.startsWith("/")) return null;
+    return { kind: value.kind, url: value.url };
+  }
+
+  function deliver(port: MessagePort, request: BridgeRequestMessage, body: unknown): void {
+    if (!isRecord(body) || !isBridgeResponse(body.response, request.id)) {
+      reply(port, makeFailure(request.id, "invalid_response", "The Thread Page bridge returned an invalid response"));
+      return;
+    }
+    const directive = body.navigate === undefined ? null : directiveOf(body.navigate);
+    if (body.response.ok && directive) {
+      reply(port, body.response);
+      if (directive.kind === "external") navigator.external(directive.url);
+      else navigator.inPlace(directive.url);
+      return;
+    }
+    navigator.release();
+    reply(port, body.response);
+  }
+
+  async function relayBridge(port: MessagePort, request: BridgeRequestMessage): Promise<void> {
+    try {
+      const first = await postBridge({ actionToken: config.actionToken, request });
+      if (isRecord(first) && isRecord(first.confirm)) {
+        const confirm = first.confirm;
+        if (typeof confirm.challenge !== "string" || typeof confirm.summary !== "string" || confirm.requestId !== request.id) {
+          reply(port, makeFailure(request.id, "invalid_response", "The Thread Page bridge returned an invalid confirmation"));
+          return;
+        }
+        const external = request.method === "navigation.openExternal";
+        const approved = await confirmer.confirm(confirm.summary, external ? () => navigator.reserveWindow() : undefined);
+        if (!approved) {
+          reply(port, makeFailure(request.id, "cancelled", "You declined this action"));
+          return;
+        }
+        const second = await postBridge({ actionToken: config.actionToken, request, confirmation: confirm.challenge });
+        deliver(port, request, second);
+        return;
+      }
+      deliver(port, request, first);
+    } catch (error) {
+      navigator.release();
+      reply(port, makeFailure(request.id, "unavailable", error instanceof Error ? error.message : "The Thread Page bridge is unavailable"));
+    }
+  }
+
+  async function uploadOne(entry: SubmitFile): Promise<{ field: string; name: string; path: string; sizeBytes: number }> {
+    const file = entry.file;
+    if (!file || typeof file.size !== "number") throw new Error("Attachment is not a file");
+    const label = file.name || "file";
+    if (file.size <= 0) throw new Error(`Attachment ${label} is empty`);
+    if (file.size > config.maxUploadBytes) throw new Error(`Attachment ${label} is larger than ${Math.round(config.maxUploadBytes / (1024 * 1024))} MiB`);
+    const content = await encodeBase64(file);
+    const response = await fetchImpl(config.uploadUrl, {
+      method: "POST",
+      credentials: "same-origin",
+      cache: "no-store",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ actionToken: config.actionToken, pageRevision: config.pageRevision, name: label, content }),
+    });
+    const body = (await response.json().catch(() => null)) as Record<string, unknown> | null;
+    if (!response.ok || !body || body.ok !== true || typeof body.name !== "string" || typeof body.path !== "string" || typeof body.sizeBytes !== "number") {
+      throw new Error((body && typeof body.message === "string" && body.message) || `Upload failed (${response.status})`);
+    }
+    return { field: String(entry.field || "file").slice(0, 128), name: body.name, path: body.path, sizeBytes: body.sizeBytes };
+  }
+
+  async function relaySubmit(port: MessagePort, data: Record<string, unknown>): Promise<void> {
+    const submissionId = typeof data.submissionId === "string" ? data.submissionId : "";
+    try {
+      const entries = (Array.isArray(data.files) ? data.files : []).slice(0, config.maxUploads) as SubmitFile[];
+      const files = [];
+      for (let index = 0; index < entries.length; index += 1) {
+        reply(port, { kind: "thread-page:submit-progress", submissionId, message: `Uploading ${index + 1} of ${entries.length}…` });
+        files.push(await uploadOne(entries[index] as SubmitFile));
+      }
+      if (files.length > 0) reply(port, { kind: "thread-page:submit-progress", submissionId, message: "Sending…" });
+      const response = await fetchImpl(config.submitUrl, {
+        method: "POST",
+        credentials: "same-origin",
+        cache: "no-store",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          actionToken: config.actionToken,
+          submissionId,
+          pageRevision: config.pageRevision,
+          title: data.title,
+          answers: data.answers,
+          files,
+        }),
+      });
+      const body = (await response.json().catch(() => ({ ok: false, message: "Invalid server response" }))) as Record<string, unknown>;
+      const ok = response.ok && body.ok === true;
+      reply(port, {
+        kind: "thread-page:submit-result",
+        submissionId,
+        ok,
+        message: typeof body.delivery === "string" ? `Sent (${body.delivery})` : "Sent",
+        error: typeof body.message === "string" ? body.message : `Request failed (${response.status})`,
+      });
+    } catch (error) {
+      reply(port, { kind: "thread-page:submit-result", submissionId, ok: false, error: error instanceof Error ? error.message : "Request failed" });
+    }
+  }
+
+  return {
+    handle(port, data) {
+      if (!isRecord(data)) return;
+      if (data.kind === "thread-page:dirty") {
+        deps.onDirty(true);
+        return;
+      }
+      if (data.kind === "thread-page:clean") {
+        deps.onDirty(false);
+        return;
+      }
+      if (data.kind === "thread-page:submit") {
+        void relaySubmit(port, data);
+        return;
+      }
+      if (!isBridgeRequest(data, config.pageRevision)) {
+        reply(port, makeFailure(data.id, "invalid_request", "Invalid Thread Page bridge request"));
+        return;
+      }
+      void relayBridge(port, data);
+    },
+  };
+}
+
+async function encodeBase64(file: Blob): Promise<string> {
+  const bytes = new Uint8Array(await file.arrayBuffer());
+  let binary = "";
+  const chunk = 0x8000;
+  for (let index = 0; index < bytes.length; index += chunk) {
+    binary += String.fromCharCode.apply(null, Array.from(bytes.subarray(index, index + chunk)));
+  }
+  return btoa(binary);
+}

package/src/serving/action-request.ts

@@ -0,0 +1,32 @@
+import type { Context } from "hono";
+import { PageError, PUBLIC_MESSAGES } from "../domain/errors.ts";
+import { verifyActionToken, type ActionToken } from "../domain/tokens/action-token.ts";
+import type { ServingContext } from "./context.ts";
+
+/**
+ * The steps every effectful route shares: a bounded JSON body, a valid action
+ * token, and a slot in the page's rate budget. spec R2.6, R2.38
+ */
+export async function readJsonBody(context: Context, maxBytes: number): Promise<unknown> {
+  const declared = Number(context.req.header("content-length") ?? "0");
+  if (Number.isFinite(declared) && declared > maxBytes) throw new PageError("request_too_large", "Request body is too large");
+  const raw = await context.req.text();
+  if (Buffer.byteLength(raw, "utf8") > maxBytes) throw new PageError("request_too_large", "Request body is too large");
+  try {
+    return JSON.parse(raw) as unknown;
+  } catch {
+    throw new PageError("invalid_json", "Request body is not valid JSON");
+  }
+}
+
+export function requireActionToken(serving: ServingContext, token: unknown): ActionToken {
+  const verified = typeof token === "string" ? verifyActionToken(token, serving.signingKey, serving.now()) : null;
+  if (!verified) throw new PageError("confirmation_invalid", PUBLIC_MESSAGES.tokenInvalid, { status: 401 });
+  return verified;
+}
+
+export function acquireRate(serving: ServingContext, session: string): () => void {
+  const release = serving.rate.acquire(session, serving.now());
+  if (!release) throw new PageError("rate_limited", PUBLIC_MESSAGES.rateLimited);
+  return release;
+}

package/src/serving/bridge/dispatcher.ts

@@ -0,0 +1,112 @@
+import { completeInvocation, decodeBridgeRequest, failure, failureFromError, resolveInvocation, type BridgeTransport } from "../../domain/capabilities/protocol.ts";
+import { PageError, PUBLIC_MESSAGES, errorText, isBridgeErrorCode } from "../../domain/errors.ts";
+import type { JsonValue } from "../../domain/json/strict-json.ts";
+import { LIMITS } from "../../domain/limits.ts";
+import { challengeMatches, mintChallenge, openChallenge } from "../../domain/tokens/confirmation.ts";
+import { acquireRate, requireActionToken } from "../action-request.ts";
+import type { ServingContext } from "../context.ts";
+import { eligibleSession } from "../session-access.ts";
+import type { CapabilityHandler, HandlerContext } from "./handler.ts";
+
+/**
+ * The one path every capability call takes. spec 03 §Confirmed effects, 05
+ *
+ *   envelope → action token → rate budget → resolve (stale, unknown, params)
+ *   → cheap refusals → confirmation (challenge out, or verify one in)
+ *   → session still eligible, page still current → handler → projection
+ */
+export interface DispatchResult {
+  readonly status: number;
+  readonly body: BridgeTransport;
+}
+
+interface Envelope {
+  readonly actionToken: string;
+  readonly request: unknown;
+  readonly confirmation: string | null;
+}
+
+export function parseEnvelope(value: unknown): Envelope {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new PageError("invalid_request", "Invalid bridge envelope");
+  const input = value as Record<string, unknown>;
+  const keys = Object.keys(input);
+  if (!keys.includes("actionToken") || !keys.includes("request") || keys.some((key) => !["actionToken", "request", "confirmation"].includes(key))) {
+    throw new PageError("invalid_request", "Invalid bridge envelope");
+  }
+  if (typeof input.actionToken !== "string" || input.actionToken.length > LIMITS.tokenChars) throw new PageError("invalid_request", "Invalid bridge envelope");
+  const confirmation = input.confirmation;
+  if (confirmation !== undefined && confirmation !== null && (typeof confirmation !== "string" || confirmation.length > LIMITS.tokenChars)) {
+    throw new PageError("invalid_request", "Invalid bridge envelope");
+  }
+  return { actionToken: input.actionToken, request: input.request, confirmation: typeof confirmation === "string" ? confirmation : null };
+}
+
+export function createDispatcher(serving: ServingContext, handlers: readonly CapabilityHandler[]) {
+  const byMethod = new Map(handlers.map((entry) => [entry.method, entry]));
+  for (const spec of serving.registry.list()) {
+    if (spec.implemented && !byMethod.has(spec.method)) throw new Error(`No handler for capability ${spec.method}`);
+  }
+
+  return async function dispatch(body: unknown): Promise<DispatchResult> {
+    let requestId: unknown;
+    let release: (() => void) | null = null;
+    try {
+      const envelope = parseEnvelope(body);
+      requestId = (envelope.request as { id?: unknown } | null)?.id;
+      const token = requireActionToken(serving, envelope.actionToken);
+      release = acquireRate(serving, token.session);
+      const request = decodeBridgeRequest(envelope.request);
+      requestId = request.id;
+      const invocation = resolveInvocation(request, serving.registry, token.revision);
+      const entry = byMethod.get(invocation.spec.method);
+      if (!entry) throw new PageError("unknown_method", `Unknown capability: ${invocation.spec.method}`);
+
+      const session = await eligibleSession(serving, token.session).catch((error: unknown) => {
+        throw PageError.is(error) && error.code === "ineligible" ? new PageError("conflict", "This session no longer accepts page actions") : error;
+      });
+      const page = await serving.pages.load(token.session);
+      if (page.revision !== token.revision) throw new PageError("stale_page", PUBLIC_MESSAGES.stalePage);
+      const context: HandlerContext = { serving, session, page, requestId: request.id };
+
+      await entry.refuse?.(invocation.params, context);
+
+      if (invocation.spec.confirmed) {
+        const binding = { session: token.session, revision: token.revision, requestId: request.id, method: request.method, params: invocation.params as JsonValue };
+        if (envelope.confirmation === null) {
+          const summary = (await entry.summarize?.(invocation.params, context)) ?? invocation.spec.description;
+          const { challenge, payload } = mintChallenge(binding, summary, serving.now(), serving.signingKey);
+          return { status: 401, body: { confirm: { requestId: request.id, summary: payload.summary, challenge } } };
+        }
+        const challenge = openChallenge(envelope.confirmation, serving.signingKey, serving.now());
+        if (!challenge || !challengeMatches(challenge, binding)) {
+          throw new PageError("confirmation_invalid", "The confirmation is expired or does not match this request");
+        }
+      }
+
+      if (page.stale && invocation.spec.effect !== "read" && invocation.spec.effect !== "navigation") {
+        throw new PageError("unavailable", PUBLIC_MESSAGES.staleCopy);
+      }
+
+      let outcome;
+      try {
+        outcome = await entry.execute(invocation.params, context);
+      } catch (error) {
+        if (PageError.is(error) && isBridgeErrorCode(error.code)) throw error;
+        serving.host.log.warn(`bridge ${request.method} for ${token.session}: ${errorText(error)}`);
+        throw new PageError("handler_error", PUBLIC_MESSAGES.handler, { cause: error });
+      }
+      const response = completeInvocation(invocation, outcome.result);
+      return { status: response.ok ? 200 : 500, body: outcome.navigate ? { response, navigate: outcome.navigate } : { response } };
+    } catch (error) {
+      if (PageError.is(error)) {
+        if (error.cause !== undefined) serving.host.log.warn(`bridge: ${error.code}: ${errorText(error.cause)}`);
+        const code = isBridgeErrorCode(error.code) ? error.code : error.code === "ineligible" || error.code === "no_page" ? "not_found" : "handler_error";
+        return { status: error.status, body: { response: failure(requestId, code, error.message) } };
+      }
+      serving.host.log.warn(`bridge: ${errorText(error)}`);
+      return { status: 500, body: { response: failureFromError(requestId, error) } };
+    } finally {
+      release?.();
+    }
+  };
+}

package/src/serving/bridge/handler.ts

@@ -0,0 +1,37 @@
+import type { NavigationDirective } from "../../domain/capabilities/protocol.ts";
+import type { SessionRecord } from "../../host/types.ts";
+import type { LoadedPage } from "../../pages/page-store.ts";
+import type { ServingContext } from "../context.ts";
+
+/**
+ * A capability's server-side half. `refuse` runs before any confirmation so
+ * cheap refusals (own session, not found) never show a dialog; `summarize`
+ * words the confirmation from validated parameters; `execute` acts.
+ */
+export interface HandlerContext {
+  readonly serving: ServingContext;
+  readonly session: SessionRecord;
+  readonly page: LoadedPage;
+  readonly requestId: string;
+}
+
+export interface HandlerOutcome<R> {
+  readonly result: R;
+  readonly navigate?: NavigationDirective;
+}
+
+export interface CapabilityHandler<P = unknown, R = unknown> {
+  readonly method: string;
+  refuse?(params: P, context: HandlerContext): Promise<void>;
+  summarize?(params: P, context: HandlerContext): Promise<string>;
+  execute(params: P, context: HandlerContext): Promise<HandlerOutcome<R>>;
+}
+
+export function handler<P, R>(definition: CapabilityHandler<P, R>): CapabilityHandler<P, R> {
+  return definition;
+}
+
+export function excerpt(text: string, max = 80): string {
+  const line = text.replace(/\s+/g, " ").trim();
+  return line.length <= max ? line : `${line.slice(0, max - 1)}…`;
+}

package/src/serving/bridge/handlers/index.ts

@@ -0,0 +1,26 @@
+import type { CapabilityHandler } from "../handler.ts";
+import { navigationOpenExternal, pagesOpen, sessionsOpenHost } from "./navigation.ts";
+import { contextGet, projectsList, providersList, sessionActivity, sessionsSnapshot, storageGet, storageSet } from "./reads.ts";
+import { projectsBrowse, projectsCreate, sessionReply, sessionsArchive, sessionsMarkRead, sessionsSend, sessionsStart, sessionsStop } from "./writes.ts";
+
+/** Every implemented capability's handler. The dispatcher checks this list against the registry at load. */
+export const ALL_HANDLERS: readonly CapabilityHandler[] = [
+  contextGet,
+  sessionActivity,
+  sessionsSnapshot,
+  projectsList,
+  providersList,
+  storageGet,
+  storageSet,
+  sessionReply,
+  sessionsSend,
+  sessionsStart,
+  sessionsStop,
+  sessionsArchive,
+  sessionsMarkRead,
+  projectsBrowse,
+  projectsCreate,
+  pagesOpen,
+  sessionsOpenHost,
+  navigationOpenExternal,
+] as CapabilityHandler[];

package/src/serving/bridge/handlers/navigation.ts

@@ -0,0 +1,43 @@
+import type { OpenExternalParams } from "../../../domain/capabilities/specs.ts";
+import { ineligibleReason } from "../../../domain/eligibility.ts";
+import { PageError } from "../../../domain/errors.ts";
+import { pageUrl } from "../../context.ts";
+import { excerpt, handler } from "../handler.ts";
+
+/**
+ * Navigation: the host validates the destination and the trusted shell
+ * performs it in place (pages, host application) or, after confirmation,
+ * to an external origin. spec R5.29–R5.34
+ */
+export const pagesOpen = handler<{ sessionId: string }, unknown>({
+  method: "pages.open",
+  async refuse(params, { serving }) {
+    const target = await serving.host.sessions.get(params.sessionId);
+    if (!target || ineligibleReason(target)) throw new PageError("not_found", "That session has no page");
+  },
+  async execute(params, { serving }) {
+    return { result: { opened: true }, navigate: { kind: "page", url: pageUrl(serving.routeBase, params.sessionId) } };
+  },
+});
+
+export const sessionsOpenHost = handler<{ sessionId: string }, unknown>({
+  method: "sessions.openHost",
+  async refuse(params, { serving }) {
+    const target = await serving.host.sessions.get(params.sessionId);
+    if (!target || target.deleted) throw new PageError("not_found", "That session is not available");
+  },
+  async execute(params, { serving }) {
+    return { result: { opened: true }, navigate: { kind: "host", url: serving.hostSessionUrl(params.sessionId) } };
+  },
+});
+
+export const navigationOpenExternal = handler<OpenExternalParams, unknown>({
+  method: "navigation.openExternal",
+  async summarize(params) {
+    const origin = new URL(params.url).origin;
+    return params.label ? `Leave this page and open “${excerpt(params.label, 60)}” at ${origin}` : `Leave this page and open ${origin}`;
+  },
+  async execute(params) {
+    return { result: { opened: true }, navigate: { kind: "external", url: new URL(params.url).href } };
+  },
+});