@unifedev/thread-pages 0.3.2 → 1.1.0

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 } };
+  },
+});

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

@@ -0,0 +1,186 @@
+import type { SessionSummary, SnapshotParams } from "../../../domain/capabilities/specs.ts";
+import { PageError } from "../../../domain/errors.ts";
+import type { JsonValue } from "../../../domain/json/strict-json.ts";
+import { LIMITS } from "../../../domain/limits.ts";
+import type { SessionRecord } from "../../../host/types.ts";
+import { ENTRY_FILE, joinPath } from "../../../pages/layout.ts";
+import { handler, type HandlerContext } from "../handler.ts";
+
+/** Read capabilities. spec 05 §Reads */
+
+export const contextGet = handler<null, unknown>({
+  method: "context.get",
+  async execute(_params, { serving, session, page }) {
+    return {
+      result: {
+        protocolVersion: 1,
+        session: { id: session.id, title: session.title.slice(0, LIMITS.titleChars), projectId: session.projectId },
+        page: { revision: page.revision, readOnly: page.stale },
+        capabilities: serving.registry.descriptors(),
+      },
+    };
+  },
+});
+
+export const sessionActivity = handler<{ limit: number }, unknown>({
+  method: "session.activity",
+  async execute(params, { serving, session }) {
+    const items = await serving.host.sessions.activity(session.id, params.limit);
+    return { result: { state: session.state, updatedAtMs: session.updatedAtMs, items } };
+  },
+});
+
+// --- sessions.snapshot -------------------------------------------------------
+
+interface Cursor {
+  readonly phase: "live" | "archived";
+  readonly offset: number;
+  readonly query: string;
+}
+
+function queryKey(params: SnapshotParams): string {
+  return `${params.projectId ?? ""}|${params.includeArchived ? 1 : 0}|${params.includeChildren ? 1 : 0}`;
+}
+
+export function encodeCursor(cursor: Cursor): string {
+  return Buffer.from(JSON.stringify(cursor), "utf8").toString("base64url");
+}
+
+export function decodeCursor(value: string, params: SnapshotParams): Cursor {
+  try {
+    const parsed = JSON.parse(Buffer.from(value, "base64url").toString("utf8")) as Partial<Cursor>;
+    if ((parsed.phase !== "live" && parsed.phase !== "archived") || !Number.isSafeInteger(parsed.offset) || (parsed.offset as number) < 0 || parsed.query !== queryKey(params)) {
+      throw new Error("mismatch");
+    }
+    return { phase: parsed.phase, offset: parsed.offset as number, query: parsed.query };
+  } catch {
+    throw new PageError("invalid_params", "The cursor does not belong to this query");
+  }
+}
+
+async function pageAvailability(context: HandlerContext, sessions: readonly SessionRecord[]): Promise<Map<string, boolean>> {
+  const { serving } = context;
+  const byHost = new Map<string, { session: string; path: string }[]>();
+  await Promise.all(
+    sessions.map(async (session) => {
+      try {
+        const location = await serving.host.sessions.storage(session.id);
+        const entries = byHost.get(location.hostId) ?? [];
+        entries.push({ session: session.id, path: joinPath(location.rootPath, ENTRY_FILE) });
+        byHost.set(location.hostId, entries);
+      } catch {
+        // No storage yet: no page.
+      }
+    }),
+  );
+  const availability = new Map<string, boolean>();
+  await Promise.all(
+    [...byHost.entries()].map(async ([hostId, entries]) => {
+      const existence = await serving.host.files.exist(hostId, entries.map((entry) => entry.path));
+      for (const entry of entries) availability.set(entry.session, existence[entry.path] === true);
+    }),
+  );
+  return availability;
+}
+
+export const sessionsSnapshot = handler<SnapshotParams, unknown>({
+  method: "sessions.snapshot",
+  async execute(params, context) {
+    const { serving } = context;
+    const start: Cursor = params.cursor ? decodeCursor(params.cursor, params) : { phase: "live", offset: 0, query: queryKey(params) };
+    const collected: SessionRecord[] = [];
+    let phase = start.phase;
+    let offset = start.offset;
+    let next: Cursor | null = null;
+    while (collected.length < params.limit) {
+      const want = params.limit - collected.length;
+      const rows = await serving.host.sessions.list({
+        ...(params.projectId ? { projectId: params.projectId } : {}),
+        archived: phase === "archived",
+        rootsOnly: !params.includeChildren,
+        offset,
+        limit: want + 1,
+      });
+      const visible = rows.filter(
+        (row) => row.visibility === "visible" && !row.deleted && row.archived === (phase === "archived") && (params.includeChildren || row.parentId === null),
+      );
+      const more = rows.length > want;
+      collected.push(...visible.slice(0, want));
+      offset += Math.min(rows.length, want);
+      if (more) {
+        next = { phase, offset, query: start.query };
+        break;
+      }
+      if (phase === "live" && params.includeArchived) {
+        phase = "archived";
+        offset = 0;
+        continue;
+      }
+      break;
+    }
+    const availability = await pageAvailability(context, collected);
+    const sessions: SessionSummary[] = collected.map((record) => ({
+      id: record.id,
+      title: record.title.slice(0, LIMITS.titleChars),
+      projectId: record.projectId,
+      parentSessionId: record.parentId,
+      status: record.state,
+      archived: record.archived,
+      page: { available: availability.get(record.id) === true, revision: availability.get(record.id) ? serving.pages.knownRevision(record.id) : null },
+      updatedAtMs: record.updatedAtMs,
+      attentionAtMs: record.attentionAtMs,
+      unread: record.unread,
+    }));
+    return { result: { sessions, nextCursor: next ? encodeCursor(next) : null, generatedAtMs: serving.now() } };
+  },
+});
+
+export const projectsList = handler<null, unknown>({
+  method: "projects.list",
+  async execute(_params, { serving }) {
+    const projects = await serving.host.projects.list();
+    return { result: { projects: projects.slice(0, LIMITS.projectsMax).map((project) => ({ id: project.id, name: project.name.slice(0, LIMITS.titleChars), kind: project.kind })) } };
+  },
+});
+
+export const providersList = handler<null, unknown>({
+  method: "providers.list",
+  async execute(_params, { serving }) {
+    const providers = await serving.host.providers.list();
+    return {
+      result: {
+        providers: providers.slice(0, LIMITS.providersMax).map((provider) => ({
+          id: provider.id,
+          displayName: provider.displayName.slice(0, LIMITS.titleChars),
+          available: provider.available,
+          models: provider.models.slice(0, LIMITS.modelsPerProvider).map((model) => ({
+            id: model.id,
+            displayName: model.displayName.slice(0, LIMITS.titleChars),
+            isDefault: model.isDefault,
+            reasoningLevels: model.reasoningLevels.slice(0, 16),
+          })),
+        })),
+      },
+    };
+  },
+});
+
+export function storageKey(session: string, key: string): string {
+  return `state:${session}:${key}`;
+}
+
+export const storageGet = handler<{ key: string }, unknown>({
+  method: "storage.get",
+  async execute(params, { serving, session }) {
+    const stored = await serving.host.kv.get(storageKey(session.id, params.key));
+    return { result: stored === undefined ? { found: false } : { found: true, value: stored } };
+  },
+});
+
+export const storageSet = handler<{ key: string; value: JsonValue }, unknown>({
+  method: "storage.set",
+  async execute(params, { serving, session }) {
+    await serving.host.kv.set(storageKey(session.id, params.key), params.value);
+    return { result: { stored: true } };
+  },
+});

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

@@ -0,0 +1,175 @@
+import type { SessionsSendParams, SessionsStartParams } from "../../../domain/capabilities/specs.ts";
+import { PageError } from "../../../domain/errors.ts";
+import { fingerprint } from "../../../domain/json/canonical.ts";
+import type { JsonValue } from "../../../domain/json/strict-json.ts";
+import { formatReplyMessage } from "../../../domain/submissions/message.ts";
+import type { SessionRecord, StartSessionArgs } from "../../../host/types.ts";
+import { excerpt, handler, type HandlerContext } from "../handler.ts";
+
+/** Writes to the page's own session, and the confirmed cross-session effects. spec 05 */
+
+interface ReplyParams {
+  title?: string;
+  mode: "queue" | "steer";
+  result: JsonValue;
+  idempotencyKey?: string;
+}
+
+export const sessionReply = handler<ReplyParams, unknown>({
+  method: "session.reply",
+  async execute(params, { serving, session, page, requestId }) {
+    const key = `${session.id}:${params.idempotencyKey ?? requestId}`;
+    const print = fingerprint({ revision: page.revision, result: params.result, mode: params.mode, title: params.title ?? null });
+    const remembered = serving.replies.remember(key, print, () => serving.host.sessions.send(session.id, formatReplyMessage(params.title, params.result), params.mode), serving.now());
+    if (remembered.kind === "conflict") throw new PageError("conflict", "This idempotency key was already used with a different reply");
+    const outcome = await remembered.outcome;
+    return { result: { delivery: outcome.delivery, duplicate: remembered.kind === "replay" } };
+  },
+});
+
+async function targetSession(context: HandlerContext, id: string): Promise<SessionRecord> {
+  const target = await context.serving.host.sessions.get(id);
+  if (!target || target.deleted) throw new PageError("not_found", "That session is not available");
+  return target;
+}
+
+export const sessionsSend = handler<SessionsSendParams, unknown>({
+  method: "sessions.send",
+  async refuse(params, context) {
+    if (params.sessionId === context.session.id) throw new PageError("invalid_params", "Use session.reply to answer this page's own session");
+    await targetSession(context, params.sessionId);
+  },
+  async summarize(params, context) {
+    const target = await targetSession(context, params.sessionId);
+    return `Send to “${excerpt(target.title, 60)}”: “${excerpt(params.prompt)}”${params.mode === "steer" ? " (interrupting its current turn)" : ""}`;
+  },
+  async execute(params, { serving }) {
+    const sent = await serving.host.sessions.send(params.sessionId, params.prompt, params.mode);
+    return { result: { sessionId: params.sessionId, delivery: sent.delivery, duplicate: false } };
+  },
+});
+
+async function resolveStart(params: SessionsStartParams, context: HandlerContext): Promise<{ args: StartSessionArgs; projectName: string; environmentLabel: string }> {
+  const projects = await context.serving.host.projects.list();
+  const project = projects.find((candidate) => candidate.id === params.projectId);
+  if (!project) throw new PageError("not_found", "That project is not available");
+  let environment: StartSessionArgs["environment"] = { kind: "project-default" };
+  let environmentLabel = "the project's default environment";
+  if (typeof params.environment === "object") {
+    const other = await targetSession(context, params.environment.sameAs);
+    if (!other.environmentId) throw new PageError("invalid_params", "That session has no environment to share");
+    environment = { kind: "reuse", environmentId: other.environmentId };
+    environmentLabel = `the environment of “${excerpt(other.title, 40)}”`;
+  }
+  return {
+    args: {
+      projectId: params.projectId,
+      prompt: params.prompt,
+      ...(params.title ? { title: params.title } : {}),
+      ...(params.providerId ? { providerId: params.providerId } : {}),
+      ...(params.model ? { model: params.model } : {}),
+      ...(params.reasoningLevel ? { reasoningLevel: params.reasoningLevel } : {}),
+      environment,
+    },
+    projectName: project.name,
+    environmentLabel,
+  };
+}
+
+export const sessionsStart = handler<SessionsStartParams, unknown>({
+  method: "sessions.start",
+  async refuse(params, context) {
+    await resolveStart(params, context);
+  },
+  async summarize(params, context) {
+    const { projectName, environmentLabel } = await resolveStart(params, context);
+    const runtime = [params.providerId, params.model, params.reasoningLevel].filter(Boolean).join(" · ") || "the project's default provider and model";
+    return `Start a session in ${projectName}: “${excerpt(params.prompt)}” — using ${runtime}, in ${environmentLabel}`;
+  },
+  async execute(params, context) {
+    const { args } = await resolveStart(params, context);
+    const started = await context.serving.host.sessions.start(args);
+    return { result: { sessionId: started.id } };
+  },
+});
+
+export const sessionsStop = handler<{ sessionId: string }, unknown>({
+  method: "sessions.stop",
+  async refuse(params, context) {
+    if (params.sessionId === context.session.id) throw new PageError("invalid_params", "A page cannot stop its own session");
+    await targetSession(context, params.sessionId);
+  },
+  async summarize(params, context) {
+    const target = await targetSession(context, params.sessionId);
+    return `Stop “${excerpt(target.title, 60)}”`;
+  },
+  async execute(params, { serving }) {
+    await serving.host.sessions.stop(params.sessionId);
+    return { result: { stopped: true } };
+  },
+});
+
+export const sessionsArchive = handler<{ sessionId: string }, unknown>({
+  method: "sessions.archive",
+  async refuse(params, context) {
+    await targetSession(context, params.sessionId);
+  },
+  async summarize(params, context) {
+    const target = await targetSession(context, params.sessionId);
+    return `Archive “${excerpt(target.title, 60)}”${params.sessionId === context.session.id ? " (this page's own session; its page will stop being served)" : ""}`;
+  },
+  async execute(params, { serving }) {
+    await serving.host.sessions.archive(params.sessionId);
+    return { result: { archived: true } };
+  },
+});
+
+export const sessionsMarkRead = handler<{ sessionId: string; read: boolean }, unknown>({
+  method: "sessions.markRead",
+  async refuse(params, context) {
+    await targetSession(context, params.sessionId);
+  },
+  async execute(params, { serving }) {
+    const after = await serving.host.sessions.markRead(params.sessionId, params.read);
+    return { result: { sessionId: params.sessionId, unread: after.unread } };
+  },
+});
+
+export const projectsBrowse = handler<null, unknown>({
+  method: "projects.browse",
+  async summarize() {
+    return "Choose a project folder on this device";
+  },
+  async execute(_params, { serving, session }) {
+    const location = await serving.host.sessions.storage(session.id);
+    const picked = await serving.host.projects.browse(location.hostId);
+    if (!picked) return { result: { selection: null } };
+    const token = serving.selections.issue({ session: session.id, hostId: location.hostId, path: picked.path }, serving.now());
+    return { result: { selection: { token, displayPath: displayPath(picked.path), hostName: picked.hostName } } };
+  },
+});
+
+function displayPath(path: string): string {
+  return path.replace(/^\/Users\/[^/]+/, "~").replace(/^\/home\/[^/]+/, "~").replace(/^[A-Za-z]:\\Users\\[^\\]+/, "~");
+}
+
+export const projectsCreate = handler<{ selectionToken: string; name?: string }, unknown>({
+  method: "projects.create",
+  async refuse(params, { serving, session }) {
+    if (!serving.selections.peek(params.selectionToken, session.id, serving.now())) {
+      throw new PageError("not_found", "That folder selection has expired; choose the folder again");
+    }
+  },
+  async summarize(params, { serving, session }) {
+    const selection = serving.selections.peek(params.selectionToken, session.id, serving.now());
+    const name = params.name ?? selection?.path.split(/[\\/]/).pop() ?? "the selected folder";
+    return `Create project “${excerpt(name, 60)}” from ${selection ? displayPath(selection.path) : "the selected folder"}`;
+  },
+  async execute(params, { serving, session }) {
+    const selection = serving.selections.redeem(params.selectionToken, session.id, serving.now());
+    if (!selection) throw new PageError("not_found", "That folder selection has expired; choose the folder again");
+    const name = params.name ?? selection.path.split(/[\\/]/).pop() ?? "New project";
+    const created = await serving.host.projects.create({ name, hostId: selection.hostId, path: selection.path });
+    return { result: { project: { id: created.id, name: created.name, kind: created.kind } } };
+  },
+});

package/src/serving/bridge/selection-store.ts

@@ -0,0 +1,58 @@
+import { randomBytes } from "node:crypto";
+import { LIMITS } from "../../domain/limits.ts";
+
+/**
+ * Folder-picker selections, held server-side so a page only ever sees an
+ * opaque token: single use, short-lived, bound to the requesting session.
+ * spec R5.35–R5.37
+ */
+export interface Selection {
+  readonly session: string;
+  readonly hostId: string;
+  readonly path: string;
+  readonly expiresAt: number;
+}
+
+export interface SelectionStore {
+  issue(selection: Omit<Selection, "expiresAt">, now: number): string;
+  /** Looks a selection up without consuming it. */
+  peek(token: string, session: string, now: number): Selection | null;
+  /** Returns and forgets the selection when the token is valid for the session. */
+  redeem(token: string, session: string, now: number): Selection | null;
+}
+
+export function createSelectionStore(): SelectionStore {
+  const selections = new Map<string, Selection>();
+
+  function prune(now: number): void {
+    for (const [token, selection] of selections) {
+      if (selection.expiresAt <= now) selections.delete(token);
+    }
+    while (selections.size > LIMITS.selectionTokens) {
+      const oldest = selections.keys().next().value;
+      if (oldest === undefined) break;
+      selections.delete(oldest);
+    }
+  }
+
+  return {
+    issue(selection, now) {
+      prune(now);
+      const token = `sel.${randomBytes(18).toString("base64url")}`;
+      selections.set(token, { ...selection, expiresAt: now + LIMITS.selectionTokenMs });
+      return token;
+    },
+    peek(token, session, now) {
+      prune(now);
+      const selection = selections.get(token);
+      return selection && selection.session === session ? selection : null;
+    },
+    redeem(token, session, now) {
+      prune(now);
+      const selection = selections.get(token);
+      if (!selection || selection.session !== session) return null;
+      selections.delete(token);
+      return selection;
+    },
+  };
+}