@unifedev/thread-pages 0.3.2 → 1.1.0

package/src/bb/bb-host.ts

@@ -0,0 +1,280 @@
+import type { BbPluginApi } from "@get-bb/plugin-sdk";
+import { PageError, PUBLIC_MESSAGES, errorText } from "../domain/errors.ts";
+import type { JsonValue } from "../domain/json/strict-json.ts";
+import type { SessionHost } from "../host/contract.ts";
+import type { ActivityItem, ProjectRecord, ProviderChoice, SessionRecord, StorageLocation } from "../host/types.ts";
+import { joinPath } from "../pages/layout.ts";
+import { activityItemsOf, asRecord, sessionStateOf } from "./activity.ts";
+import { createPublicOrigin } from "./public-origin.ts";
+
+/**
+ * The bb implementation of the host contract. Everything bb-shaped stops
+ * here: thread records are projected into session records, list results are
+ * reduced to the fields the product needs, and errors become `PageError`s.
+ * spec 08
+ */
+export function createBbHost(bb: BbPluginApi): SessionHost {
+  const publicOrigin = createPublicOrigin(bb);
+
+  async function pendingInteraction(threadId: string): Promise<boolean> {
+    try {
+      const listed = (await bb.sdk.threads.interactions.list({ threadId })) as unknown;
+      const record = asRecord(listed);
+      const interactions = Array.isArray(listed) ? listed : Array.isArray(record?.interactions) ? record.interactions : [];
+      return interactions.length > 0;
+    } catch {
+      return false;
+    }
+  }
+
+  function projectThread(thread: Record<string, unknown>, hasPendingInteraction: boolean): SessionRecord {
+    return {
+      id: String(thread.id),
+      title: (typeof thread.title === "string" && thread.title) || (typeof thread.titleFallback === "string" && thread.titleFallback) || "Untitled",
+      projectId: typeof thread.projectId === "string" ? thread.projectId : null,
+      state: sessionStateOf(thread, hasPendingInteraction),
+      visibility: thread.visibility === "hidden" ? "hidden" : "visible",
+      parentId: typeof thread.parentThreadId === "string" ? thread.parentThreadId : null,
+      forkOfId: typeof thread.sourceThreadId === "string" ? thread.sourceThreadId : null,
+      archived: thread.archivedAt !== null && thread.archivedAt !== undefined,
+      deleted: thread.deletedAt !== null && thread.deletedAt !== undefined,
+      updatedAtMs: typeof thread.updatedAt === "number" ? Math.max(0, Math.trunc(thread.updatedAt)) : 0,
+      attentionAtMs: typeof thread.latestAttentionAt === "number" ? Math.max(0, Math.trunc(thread.latestAttentionAt)) : 0,
+      unread: unreadOf(thread),
+      environmentId: typeof thread.environmentId === "string" ? thread.environmentId : null,
+    };
+  }
+
+  async function getThread(id: string): Promise<Record<string, unknown> | null> {
+    try {
+      const thread = (await bb.sdk.threads.get({ threadId: id })) as unknown;
+      return asRecord(thread);
+    } catch (error) {
+      if (isNotFound(error)) return null;
+      throw hostUnavailable(error);
+    }
+  }
+
+  const host: SessionHost = {
+    sessions: {
+      async get(id) {
+        const thread = await getThread(id);
+        if (!thread) return null;
+        const idle = sessionStateOf(thread, false) === "idle";
+        return projectThread(thread, idle ? await pendingInteraction(id) : false);
+      },
+      async list(query) {
+        const rows = (await bb.sdk.threads.list({
+          ...(query.projectId ? { projectId: query.projectId } : {}),
+          // bb lists archived and live threads together unless told which; always say.
+          archived: query.archived,
+          ...(query.rootsOnly ? { hasParent: false } : {}),
+          limit: query.limit,
+          offset: query.offset,
+        })) as unknown;
+        if (!Array.isArray(rows)) return [];
+        return rows
+          .map((row) => asRecord(row))
+          .filter((row): row is Record<string, unknown> => row !== null)
+          .map((row) => projectThread(row, row.hasPendingInteraction === true));
+      },
+      async send(id, text, mode) {
+        const before = await getThread(id);
+        const wasWorking = before ? sessionStateOf(before, false) === "working" : false;
+        const sent = await bb.sdk.threads.send({
+          threadId: id,
+          mode: mode === "steer" ? "steer-if-active" : "queue-if-active",
+          input: [{ type: "text", text, mentions: [] }],
+        });
+        if (sent.delivery === "queued") return { delivery: "queued" };
+        return { delivery: mode === "steer" && wasWorking ? "steered" : "started" };
+      },
+      async start(args) {
+        const spawned = await bb.sdk.threads.spawn({
+          projectId: args.projectId,
+          prompt: args.prompt,
+          ...(args.title ? { title: args.title } : {}),
+          ...(args.providerId ? { providerId: args.providerId } : {}),
+          ...(args.model ? { model: args.model } : {}),
+          ...(args.reasoningLevel ? { reasoningLevel: args.reasoningLevel as never } : {}),
+          environment: args.environment.kind === "reuse" ? { type: "reuse", environmentId: args.environment.environmentId } : { type: "project-default" },
+          // The reader started this work: a visible root, never a hidden helper.
+          visibility: "visible",
+        });
+        return { id: spawned.id };
+      },
+      async stop(id) {
+        await bb.sdk.threads.stop({ threadId: id });
+      },
+      async archive(id) {
+        await bb.sdk.threads.archive({ threadId: id });
+      },
+      async markRead(id, read) {
+        const after = (read ? await bb.sdk.threads.markRead({ threadId: id }) : await bb.sdk.threads.markUnread({ threadId: id })) as unknown;
+        const record = asRecord(after);
+        return { unread: record ? unreadOf(record) : !read };
+      },
+      async activity(id, limit): Promise<ActivityItem[]> {
+        const events = (await bb.sdk.threads.events.list({
+          threadId: id,
+          order: "desc",
+          limit: "80",
+          types: ["item/started", "item/completed"],
+        })) as unknown;
+        return activityItemsOf(Array.isArray(events) ? events : [], limit);
+      },
+      async storage(id): Promise<StorageLocation> {
+        try {
+          const location = await bb.sdk.threads.storageLocation({ threadId: id });
+          return { hostId: location.hostId, rootPath: location.storageRootPath };
+        } catch (error) {
+          if (isNotFound(error)) throw new PageError("not_found", "That session is not available", { cause: error });
+          throw hostUnavailable(error);
+        }
+      },
+    },
+    projects: {
+      async list(): Promise<ProjectRecord[]> {
+        const projects = (await bb.sdk.projects.list({ includePersonal: true })) as unknown;
+        if (!Array.isArray(projects)) return [];
+        return projects
+          .map((raw) => asRecord(raw))
+          .filter((project): project is Record<string, unknown> => project !== null && typeof project.id === "string")
+          .map((project) => ({
+            id: String(project.id),
+            name: typeof project.name === "string" ? project.name : "Untitled",
+            kind: project.kind === "personal" ? "personal" : "standard",
+            hostId: defaultHostId(project.sources),
+          }));
+      },
+      async browse(hostId) {
+        const picked = await bb.sdk.hosts.pickFolder({ hostId, clientHostId: hostId });
+        if (!picked.path) return null;
+        const hostRecord = await bb.sdk.hosts.get({ hostId }).catch(() => null);
+        return { path: picked.path, hostName: hostRecord?.name ?? "this device" };
+      },
+      async create(args) {
+        const created = await bb.sdk.projects.create({ name: args.name, source: { type: "local_path", hostId: args.hostId, path: args.path } });
+        return { id: created.id, name: created.name, kind: created.kind === "personal" ? "personal" : "standard", hostId: args.hostId };
+      },
+    },
+    providers: {
+      async list(): Promise<ProviderChoice[]> {
+        let providers: unknown;
+        try {
+          providers = await bb.sdk.providers.list();
+        } catch (error) {
+          throw new PageError("unavailable", "Providers cannot be listed right now", { cause: error });
+        }
+        if (!Array.isArray(providers)) throw new PageError("unavailable", "Providers cannot be listed right now");
+        const choices = await Promise.all(
+          providers
+            .map((raw) => asRecord(raw))
+            .filter((provider): provider is Record<string, unknown> => provider !== null && typeof provider.id === "string")
+            .map(async (provider) => {
+              const id = String(provider.id);
+              const catalog = (await bb.sdk.providers.models({ providerId: id }).catch(() => null)) as unknown;
+              const models = asRecord(catalog)?.models;
+              return {
+                id,
+                displayName: typeof provider.displayName === "string" ? provider.displayName : id,
+                available: provider.available !== false,
+                models: (Array.isArray(models) ? models : [])
+                  .map((raw) => asRecord(raw))
+                  .filter((model): model is Record<string, unknown> => model !== null && typeof model.id === "string")
+                  .map((model) => ({
+                    id: String(model.id),
+                    displayName: typeof model.displayName === "string" ? model.displayName : String(model.id),
+                    isDefault: model.isDefault === true,
+                    reasoningLevels: (Array.isArray(model.supportedReasoningEfforts) ? model.supportedReasoningEfforts : [])
+                      .map((effort) => asRecord(effort)?.reasoningEffort)
+                      .filter((level): level is string => typeof level === "string"),
+                  })),
+              };
+            }),
+        );
+        return choices;
+      },
+    },
+    files: {
+      async read(location, relativePath) {
+        try {
+          const file = await bb.sdk.files.read({ hostId: location.hostId, path: joinPath(location.rootPath, relativePath), rootPath: location.rootPath });
+          const bytes = file.contentEncoding === "base64" ? Buffer.from(file.content, "base64") : Buffer.from(file.content, "utf8");
+          return { bytes, sha256: file.sha256, modifiedAtMs: typeof file.modifiedAtMs === "number" ? file.modifiedAtMs : null };
+        } catch (error) {
+          if (isNotFound(error)) return null;
+          throw hostUnavailable(error);
+        }
+      },
+      async write(location, relativePath, bytes, options) {
+        try {
+          const written = await bb.sdk.files.write({
+            hostId: location.hostId,
+            path: joinPath(location.rootPath, relativePath),
+            rootPath: location.rootPath,
+            content: Buffer.from(bytes).toString("base64"),
+            contentEncoding: "base64",
+            createParents: true,
+            ...(options.onlyIfAbsent ? { expectedSha256: null } : {}),
+            mode: 0o644,
+          });
+          return written.outcome === "written" ? "written" : "exists";
+        } catch (error) {
+          if (options.onlyIfAbsent && isConflict(error)) return "exists";
+          throw hostUnavailable(error);
+        }
+      },
+      async exist(hostId, absolutePaths) {
+        if (absolutePaths.length === 0) return {};
+        try {
+          const result = await bb.sdk.hosts.pathsExist({ hostId, paths: [...absolutePaths] });
+          return Object.fromEntries(absolutePaths.map((path) => [path, result.existence[path] === true]));
+        } catch {
+          return Object.fromEntries(absolutePaths.map((path) => [path, false]));
+        }
+      },
+    },
+    kv: {
+      get: (key) => bb.storage.kv.get<JsonValue>(key),
+      set: (key, value) => bb.storage.kv.set(key, value),
+      delete: (key) => bb.storage.kv.delete(key),
+    },
+    origin: { public: publicOrigin },
+    log: bb.log,
+  };
+  return host;
+}
+
+/** bb marks a thread unread when it asked for attention after the reader last looked. */
+function unreadOf(thread: Record<string, unknown>): boolean {
+  const attention = typeof thread.latestAttentionAt === "number" ? thread.latestAttentionAt : 0;
+  const read = typeof thread.lastReadAt === "number" ? thread.lastReadAt : null;
+  return attention > 0 && (read === null || read < attention);
+}
+
+function defaultHostId(sources: unknown): string | null {
+  if (!Array.isArray(sources)) return null;
+  const records = sources.map((raw) => asRecord(raw)).filter((source): source is Record<string, unknown> => source !== null);
+  const chosen = records.find((source) => source.isDefault === true) ?? records[0];
+  return chosen && typeof chosen.hostId === "string" ? chosen.hostId : null;
+}
+
+function isNotFound(error: unknown): boolean {
+  const record = asRecord(error);
+  if (record) {
+    if (record.code === "ENOENT" || record.status === 404) return true;
+    const body = asRecord(record.body);
+    if (body?.code === "ENOENT" || body?.code === "not_found") return true;
+  }
+  return /\b(enoent|not found|does not exist|no such file)\b/i.test(errorText(error));
+}
+
+function isConflict(error: unknown): boolean {
+  const record = asRecord(error);
+  return record?.status === 409 || /\b(conflict|already exists|exists)\b/i.test(errorText(error));
+}
+
+function hostUnavailable(error: unknown): PageError {
+  return PageError.is(error) ? error : new PageError("unavailable", PUBLIC_MESSAGES.unavailable, { cause: error });
+}

package/src/bb/public-origin.ts

@@ -0,0 +1,45 @@
+import type { BbPluginApi } from "@get-bb/plugin-sdk";
+
+/**
+ * The origin a reader can reach this bb at from anywhere: the Connect
+ * plugin's public URL when paired, else the operator-configured app URL,
+ * else nothing (local-only). Only a positive answer is cached, so a link is
+ * never stale for long after Connect comes up. spec R6.7, R8.15
+ */
+export function createPublicOrigin(bb: BbPluginApi, cacheMs = 30_000): () => Promise<string | null> {
+  let cached: { at: number; origin: string } | null = null;
+  return async () => {
+    const now = Date.now();
+    if (cached && now - cached.at < cacheMs) return cached.origin;
+    const origin = (await connectOrigin(bb)) ?? configuredOrigin(bb);
+    cached = origin ? { at: now, origin } : null;
+    return origin;
+  };
+}
+
+async function connectOrigin(bb: BbPluginApi): Promise<string | null> {
+  try {
+    const status = (await bb.sdk.plugins.callRpc({
+      pluginId: "connect",
+      method: "status",
+      input: null,
+      // Connect validates its own output; we read two fields.
+      outputSchema: { parse: (value: unknown) => value } as never,
+    })) as { state?: unknown; url?: unknown } | null;
+    if (status && status.state === "connected" && typeof status.url === "string") {
+      return new URL(status.url).origin;
+    }
+  } catch {
+    // Connect absent, disabled or unpaired: a normal local-only answer.
+  }
+  return null;
+}
+
+function configuredOrigin(bb: BbPluginApi): string | null {
+  try {
+    const url = bb.server.experimental_appUrl;
+    return url ? new URL(url).origin : null;
+  } catch {
+    return null;
+  }
+}

package/src/config/settings.ts

@@ -0,0 +1,82 @@
+import type { BbPluginApi } from "@get-bb/plugin-sdk";
+import { DEFAULT_AGENT_INSTRUCTION } from "../agent/instruction.ts";
+import { DEFAULT_PAGE_SEED } from "../agent/seed/seed.ts";
+
+/**
+ * The five settings and nothing more. spec 07
+ *
+ * Read live: a change applies to the next request without a restart (R7.5).
+ * Neither the seed nor the instruction ever touches an existing page (R7.1).
+ */
+export interface Settings {
+  readonly agentInstructions: boolean;
+  readonly agentInstructionText: string;
+  readonly pageSeedHtml: string;
+  readonly workingLabel: string;
+  readonly homeSessionId: string;
+}
+
+export const DEFAULT_WORKING_LABEL = "Working — this is the last saved version";
+
+export interface LiveSettings {
+  current(): Settings;
+  set(values: Partial<{ [K in keyof Settings]: Settings[K] | null }>): Promise<Settings>;
+}
+
+export async function defineSettings(bb: BbPluginApi): Promise<LiveSettings> {
+  const handle = bb.settings.define({
+    agentInstructions: {
+      type: "boolean",
+      label: "Agent instructions",
+      description: "Inject the standing Thread Pages instruction into every eligible new session.",
+      default: false,
+    },
+    agentInstructionText: {
+      type: "string",
+      label: "Agent instruction text",
+      description: "What eligible new sessions receive when Agent instructions is on. Changing it affects future sessions only.",
+      experimental_multiline: true,
+      default: DEFAULT_AGENT_INSTRUCTION,
+    },
+    pageSeedHtml: {
+      type: "string",
+      label: "New-page seed",
+      description: "The complete HTML a new page starts from. {{TITLE}} is replaced, escaped. Existing pages are never rewritten.",
+      experimental_multiline: true,
+      default: DEFAULT_PAGE_SEED,
+    },
+    workingLabel: {
+      type: "string",
+      label: "Working indicator text",
+      description: "Shown in the page header while the owning session is mid-turn. Blank hides the indicator.",
+      default: DEFAULT_WORKING_LABEL,
+    },
+    homeSessionId: {
+      type: "string",
+      label: "Home page session",
+      description: "The session whose page is home; every other page links back to it. Set with `bb thread-page home`.",
+      default: "",
+    },
+  });
+  let current = normalize(await handle.get());
+  handle.onChange((next) => {
+    current = normalize(next);
+  });
+  return {
+    current: () => current,
+    async set(values) {
+      current = normalize(await handle.experimental_set(values));
+      return current;
+    },
+  };
+}
+
+function normalize(values: { agentInstructions: boolean; agentInstructionText: string; pageSeedHtml: string; workingLabel: string; homeSessionId: string }): Settings {
+  return {
+    agentInstructions: values.agentInstructions === true,
+    agentInstructionText: values.agentInstructionText,
+    pageSeedHtml: values.pageSeedHtml,
+    workingLabel: values.workingLabel.trim(),
+    homeSessionId: values.homeSessionId.trim(),
+  };
+}

package/src/domain/capabilities/contract.ts

@@ -0,0 +1,48 @@
+import type { JsonValue, Validation } from "../json/strict-json.ts";
+
+/**
+ * What every capability declares. spec R5.1
+ *
+ * A spec is pure: it names the capability, classes its effect, and validates
+ * its parameters and its result. Execution and confirmation wording live in
+ * the server-side handler, which is the only place with host access.
+ */
+/**
+ * `reader-state` changes only what the reader sees about a session — its
+ * read mark — never the session's work; it is not confirmed. spec R5.7a
+ */
+export const EFFECT_CLASSES = ["read", "own-session-write", "cross-session-write", "destructive", "navigation", "device", "reader-state"] as const;
+export type EffectClass = (typeof EFFECT_CLASSES)[number];
+
+/** Effects that must be confirmed in trusted chrome. spec R5.7 */
+export const CONFIRMED_EFFECTS: ReadonlySet<EffectClass> = new Set(["cross-session-write", "destructive", "device"]);
+
+export interface CapabilityDoc {
+  /** One paragraph on the parameters, for the guide. */
+  readonly params: string;
+  /** One paragraph on the result, for the guide. */
+  readonly result: string;
+  /** Anything an author must know: refusals, defaults, confirmation wording. */
+  readonly notes?: string;
+}
+
+export interface CapabilitySpec<Params = unknown, Result = unknown> {
+  readonly method: string;
+  readonly description: string;
+  readonly effect: EffectClass;
+  readonly confirmed: boolean;
+  /** `false` means the contract exists but the host does not implement it: `unknown_method`. spec R5.6 */
+  readonly implemented: boolean;
+  readonly validateParams: (value: JsonValue | undefined) => Validation<Params>;
+  readonly validateResult: (value: unknown) => Validation<Result>;
+  readonly doc: CapabilityDoc;
+}
+
+export type AnyCapabilitySpec = CapabilitySpec<any, any>;
+
+/** What `context.get` reports about one capability. spec R5.9 */
+export interface CapabilityDescriptor {
+  readonly method: string;
+  readonly effect: EffectClass;
+  readonly confirmation: "none" | "required";
+}

package/src/domain/capabilities/index.ts

@@ -0,0 +1,10 @@
+import { createRegistry } from "./registry.ts";
+import { ALL_CAPABILITIES } from "./specs.ts";
+
+export * from "./contract.ts";
+export * from "./protocol.ts";
+export * from "./registry.ts";
+export * from "./specs.ts";
+
+/** The registry the host serves: every spec, with `implemented` deciding the roster. */
+export const capabilityRegistry = createRegistry(ALL_CAPABILITIES);

package/src/domain/capabilities/protocol.ts

@@ -0,0 +1,113 @@
+import { boundedMessage, isBridgeErrorCode, PageError, type BridgeErrorCode } from "../errors.ts";
+import { isMethodName, isRequestId, isRevision } from "../ids.ts";
+import { isJsonObject, validateJson, type JsonValue } from "../json/strict-json.ts";
+import { LIMITS } from "../limits.ts";
+import type { CapabilityRegistry } from "./registry.ts";
+import type { AnyCapabilitySpec } from "./contract.ts";
+import { unknownMethodMessage } from "./renamed.ts";
+
+/**
+ * The bridge protocol: what a page sends over the port and what it gets back.
+ * Version 1. spec R3.9, R4.28, R5.38
+ */
+export const BRIDGE_PROTOCOL_VERSION = 1 as const;
+
+export interface BridgeRequest {
+  readonly v: 1;
+  readonly id: string;
+  readonly method: string;
+  readonly params: JsonValue;
+  readonly pageRevision: string;
+}
+
+export interface BridgeSuccess {
+  readonly v: 1;
+  readonly id: string;
+  readonly ok: true;
+  readonly result: JsonValue;
+}
+
+export interface BridgeFailure {
+  readonly v: 1;
+  readonly id: string;
+  readonly ok: false;
+  readonly error: { readonly code: BridgeErrorCode; readonly message: string };
+}
+
+export type BridgeResponse = BridgeSuccess | BridgeFailure;
+
+/** What the shell receives from `POST /bridge`. */
+export type BridgeTransport =
+  | { readonly response: BridgeResponse; readonly navigate?: NavigationDirective }
+  | { readonly confirm: { readonly requestId: string; readonly summary: string; readonly challenge: string } };
+
+/** A host-validated destination the trusted shell navigates to. spec R5.29–R5.34 */
+export type NavigationDirective =
+  | { readonly kind: "page"; readonly url: string }
+  | { readonly kind: "host"; readonly url: string }
+  | { readonly kind: "external"; readonly url: string };
+
+export function decodeBridgeRequest(input: unknown): BridgeRequest {
+  const checked = validateJson(input);
+  if (!checked.ok) {
+    const tooLarge = checked.issues.some((issue) => issue.code === "too_large");
+    throw new PageError(tooLarge ? "request_too_large" : "invalid_request", tooLarge ? "Bridge request is too large" : "Bridge request is not strict JSON");
+  }
+  const value = checked.value;
+  if (!isJsonObject(value)) throw new PageError("invalid_request", "Bridge request must be an object");
+  const keys = Object.keys(value).sort().join(",");
+  if (keys !== "id,method,pageRevision,params,v") throw new PageError("invalid_request", "Bridge request has the wrong shape");
+  if (value.v !== BRIDGE_PROTOCOL_VERSION) throw new PageError("unsupported_version", "Unsupported bridge protocol version");
+  if (!isRequestId(value.id)) throw new PageError("invalid_request", "Invalid request id");
+  if (!isMethodName(value.method)) throw new PageError("invalid_request", "Invalid method name");
+  if (!isRevision(value.pageRevision)) throw new PageError("invalid_request", "Invalid page revision");
+  return { v: 1, id: value.id, method: value.method, params: value.params as JsonValue, pageRevision: value.pageRevision };
+}
+
+export function safeRequestId(value: unknown): string {
+  return isRequestId(value) ? value : "invalid";
+}
+
+export function failure(id: unknown, code: BridgeErrorCode, message: string): BridgeFailure {
+  return { v: 1, id: safeRequestId(id), ok: false, error: { code, message: boundedMessage(message) } };
+}
+
+export function failureFromError(id: unknown, error: unknown): BridgeFailure {
+  if (PageError.is(error) && isBridgeErrorCode(error.code)) return failure(id, error.code, error.message);
+  return failure(id, "handler_error", "Could not execute the page action.");
+}
+
+export interface ResolvedInvocation<Params = unknown> {
+  readonly request: BridgeRequest;
+  readonly spec: AnyCapabilitySpec;
+  readonly params: Params;
+}
+
+/**
+ * Looks a request up in the registry and validates its parameters. Stale
+ * revisions are refused before the method is even looked at. spec R2.13
+ */
+export function resolveInvocation(request: BridgeRequest, registry: CapabilityRegistry, currentRevision: string): ResolvedInvocation {
+  if (request.pageRevision !== currentRevision) throw new PageError("stale_page", "This page changed; reload it before responding.");
+  const spec = registry.get(request.method);
+  if (!spec || !spec.implemented) throw new PageError("unknown_method", unknownMethodMessage(request.method));
+  const params = spec.validateParams(request.params);
+  if (!params.ok) {
+    const first = params.issues[0];
+    throw new PageError("invalid_params", `Invalid parameters for ${spec.method}${first ? ` at ${first.path}: ${first.message}` : ""}`);
+  }
+  return { request, spec, params: params.value };
+}
+
+/** Projects a handler result through the spec's validator into a response. spec R5.3 */
+export function completeInvocation(invocation: ResolvedInvocation, result: unknown): BridgeResponse {
+  const projected = invocation.spec.validateResult(result);
+  if (!projected.ok) return failure(invocation.request.id, "invalid_result", `Invalid result for ${invocation.spec.method}`);
+  const json = validateJson(projected.value);
+  if (!json.ok) return failure(invocation.request.id, "invalid_result", `Result for ${invocation.spec.method} is not strict JSON`);
+  const response: BridgeSuccess = { v: 1, id: invocation.request.id, ok: true, result: json.value };
+  if (Buffer.byteLength(JSON.stringify(response), "utf8") > LIMITS.capabilityPayloadBytes) {
+    return failure(invocation.request.id, "response_too_large", "Bridge response is too large");
+  }
+  return response;
+}

package/src/domain/capabilities/registry.ts

@@ -0,0 +1,48 @@
+import { isMethodName } from "../ids.ts";
+import { CONFIRMED_EFFECTS, EFFECT_CLASSES, type AnyCapabilitySpec, type CapabilityDescriptor } from "./contract.ts";
+
+export interface CapabilityRegistry {
+  get(method: string): AnyCapabilitySpec | undefined;
+  list(): readonly AnyCapabilitySpec[];
+  /** The roster a page may discover: implemented capabilities only. spec R5.9 */
+  descriptors(): readonly CapabilityDescriptor[];
+}
+
+/**
+ * Builds a registry and enforces the invariants no capability may break:
+ * unique, well-formed names; a known effect class; confirmation exactly where
+ * the effect class demands it (navigation may go either way). spec R5.7, R5.8
+ */
+export function createRegistry(specs: readonly AnyCapabilitySpec[]): CapabilityRegistry {
+  const byMethod = new Map<string, AnyCapabilitySpec>();
+  for (const spec of specs) {
+    if (!isMethodName(spec.method)) throw new TypeError(`Invalid capability name: ${spec.method}`);
+    if (byMethod.has(spec.method)) throw new TypeError(`Duplicate capability: ${spec.method}`);
+    if (!EFFECT_CLASSES.includes(spec.effect)) throw new TypeError(`Invalid effect for ${spec.method}`);
+    if (CONFIRMED_EFFECTS.has(spec.effect) && !spec.confirmed) {
+      throw new TypeError(`${spec.method} has a ${spec.effect} effect and must be confirmed`);
+    }
+    if ((spec.effect === "read" || spec.effect === "own-session-write" || spec.effect === "reader-state") && spec.confirmed) {
+      throw new TypeError(`${spec.method} is a ${spec.effect} and must not be confirmed`);
+    }
+    if (typeof spec.description !== "string" || spec.description.trim().length === 0 || spec.description.length > 240) {
+      throw new TypeError(`Invalid description for ${spec.method}`);
+    }
+    byMethod.set(spec.method, Object.freeze({ ...spec }));
+  }
+  const list = Object.freeze([...byMethod.values()]);
+  const descriptors = Object.freeze(
+    list
+      .filter((spec) => spec.implemented)
+      .map((spec): CapabilityDescriptor => ({
+        method: spec.method,
+        effect: spec.effect,
+        confirmation: spec.confirmed ? "required" : "none",
+      })),
+  );
+  return Object.freeze({
+    get: (method: string) => byMethod.get(method),
+    list: () => list,
+    descriptors: () => descriptors,
+  });
+}

package/src/domain/capabilities/renamed.ts

@@ -0,0 +1,34 @@
+/**
+ * Names the 0.3.x API answered for, when a page still calls it. spec R5.38–R5.41
+ *
+ * 1.0.0 renamed the whole page-facing surface with no migration path, and the
+ * only signal a page got back was `unknown_method: threads.spawn` — which
+ * reads as "this host cannot do that" rather than "this is called something
+ * else now". Naming the replacement turns a debugging session into a one-line
+ * fix. There are no aliases and there will be none: the old name still fails.
+ */
+export const RENAMED_METHODS: Readonly<Record<string, string>> = Object.freeze({
+  "threads.spawn": "sessions.start",
+  "threads.snapshot": "sessions.snapshot",
+  "threads.send": "sessions.send",
+  "threads.stop": "sessions.stop",
+  "threads.archive": "sessions.archive",
+  "threads.activity": "session.activity",
+  "threads.reply": "session.reply",
+  "threads.openPage": "pages.open",
+  "threads.openBb": "sessions.openHost",
+  "thread.get": "context.get",
+  "thread.reply": "session.reply",
+  "thread.activity": "session.activity",
+  "page.storage.get": "storage.get",
+  "page.storage.set": "storage.set",
+  "navigation.open": "navigation.openExternal",
+});
+
+/** The `unknown_method` message for a method, naming its replacement when there is one. */
+export function unknownMethodMessage(method: string): string {
+  const replacement = RENAMED_METHODS[method];
+  return replacement
+    ? `Unknown capability: ${method} (renamed to ${replacement} in 1.0; there is no alias)`
+    : `Unknown capability: ${method}`;
+}