@k2b/cloud 0.42.0 → 0.44.0

package/src/browser/app-access-recovery.ts

@@ -0,0 +1,44 @@
+import { type ToastHandle, toast } from "@k2b/ui";
+import { appAccessMessages } from "../access/app-access-messages";
+import { APP_ACCESS_REVOKED_EVENT } from "./live-websocket";
+import { reloadOnce } from "./reload";
+
+/** Keep an already-open page coherent when its next request or live connection loses app access. */
+export const installAppAccessRecovery = (app: { id: string; routes: readonly string[] }): (() => void) => {
+  let active = true;
+  let notice: ToastHandle | undefined;
+  const recover = () => {
+    if (!active) return;
+    const url = new URL(window.location.href);
+    url.searchParams.set("_cloud_access", "revoked");
+    window.history.replaceState(window.history.state, "", url.pathname + url.search + url.hash);
+    if (!reloadOnce(`app-access:${app.id}`) && !notice) {
+      const t = appAccessMessages.resolve([document.documentElement.lang]).t;
+      notice = toast(t.accessChanged, { duration: 0, action: { label: t.reload, onClick: () => window.location.reload() } });
+    }
+  };
+  const original = window.fetch;
+  const wrapped: typeof window.fetch = Object.assign(async (...args: Parameters<typeof window.fetch>) => {
+    const response = await original.apply(window, args);
+    if (response.status === 403 && response.headers.get("X-Cloud-App-Access-Denied") === app.id) {
+      const input = args[0];
+      const url = new URL(input instanceof Request ? input.url : String(input), window.location.href);
+      if (url.origin === window.location.origin) recover();
+    }
+    return response;
+  }, original);
+  window.fetch = wrapped;
+  const revoked = (event: Event) => {
+    if (!(event instanceof CustomEvent) || typeof event.detail !== "string") return;
+    const url = new URL(event.detail, window.location.href);
+    if (url.host !== window.location.host || !["ws:", "wss:"].includes(url.protocol)) return;
+    if (app.routes.some((prefix) => url.pathname === prefix || url.pathname.startsWith(`${prefix.replace(/\/$/, "")}/`))) recover();
+  };
+  window.addEventListener(APP_ACCESS_REVOKED_EVENT, revoked);
+  return () => {
+    active = false;
+    notice?.dismiss();
+    if (window.fetch === wrapped) window.fetch = original;
+    window.removeEventListener(APP_ACCESS_REVOKED_EVENT, revoked);
+  };
+};

package/src/browser/app-session.ts

@@ -1,8 +1,11 @@
 import { PWA_AUTH_PATH, PWA_SCOPE } from "../contracts/pwa-paths";
+import { pwaDrafts } from "./pwa-drafts";
 
 export type AppSessionRenewal = {
   /** The page has a valid app session now. */
   ok: boolean;
+  /** Registered release identities of mobile page owners and Core shared assets. */
+  builds?: Record<string, string>;
   /** Android shares Chrome's cookies with the app, so the web session there may belong to another account. */
   otherAccount?: { name: string };
 };
@@ -26,6 +29,7 @@ const call = async (): Promise<AppSessionRenewal & { renewed: boolean }> => {
   if (response.status === 401) {
     // The phone was removed or its pairing ended. Core has already deleted the device key with this answer, so
     // a reload could only show the generic pairing view; the pairing view for a signed-out phone says why.
+    pwaDrafts.clearAll();
     location.replace(`${PWA_SCOPE}?pwa=ended`);
     return { ok: false, renewed: false };
   }
@@ -45,7 +49,11 @@ const call = async (): Promise<AppSessionRenewal & { renewed: boolean }> => {
   const other = "otherAccount" in body ? body.otherAccount : undefined;
   const otherAccount =
     typeof other === "object" && other !== null && "name" in other && typeof other.name === "string" ? { name: other.name } : undefined;
-  return { ok: true, renewed: body.renewed, otherAccount };
+  const builds =
+    "builds" in body && typeof body.builds === "object" && body.builds !== null
+      ? Object.fromEntries(Object.entries(body.builds).filter((entry): entry is [string, string] => typeof entry[1] === "string"))
+      : undefined;
+  return { ok: true, renewed: body.renewed, otherAccount, builds };
 };
 
 let running: Promise<AppSessionRenewal> | undefined;
@@ -59,8 +67,11 @@ export const renewAppSession = (): Promise<AppSessionRenewal> => {
     try {
       const first = await call();
       // After a rotation, a second call presents the new key and retires the old one.
-      if (first.renewed) await call();
-      return { ok: first.ok, otherAccount: first.otherAccount };
+      if (first.renewed) {
+        const confirmed = await call();
+        if (!confirmed.ok) return confirmed;
+      }
+      return { ok: first.ok, otherAccount: first.otherAccount, builds: first.builds };
     } finally {
       running = undefined;
     }

package/src/browser/cloud-id.ts

@@ -0,0 +1,86 @@
+import { i18n } from "@k2b/stdlib";
+import { type DropdownItem, toast, useLocale } from "@k2b/ui";
+import { createMemo, onMount } from "solid-js";
+import type { CloudResourceRef } from "../contracts/capabilities";
+import { cloudResourceHref } from "../contracts/resource-href";
+import { cloudOrigin } from "./resource-links";
+
+export const cloudIdMessages = i18n.define({
+  baseLocale: "en",
+  messages: {
+    en: {
+      copy: "Copy Cloud ID",
+      copied: "Cloud ID copied",
+      copyFailed: "Could not copy the Cloud ID",
+    },
+    de: {
+      copy: "Cloud-ID kopieren",
+      copied: "Cloud-ID kopiert",
+      copyFailed: "Cloud-ID konnte nicht kopiert werden",
+    },
+  },
+});
+
+type ClipboardModule = typeof import("./resource-clipboard");
+// The clipboard contract validates with Zod, which stays out of an island's first load. It loads once the page is
+// idle, so a copy usually writes the structured reference inside the click that asked for it.
+let clipboardModule: ClipboardModule | undefined;
+const loadClipboard = () => import("./resource-clipboard").then((module) => (clipboardModule = module));
+
+/** One entry of the menu; `label` names the resource when a menu offers several, such as a message and its conversation. */
+export type CloudIdTarget = { ref: CloudResourceRef; label?: string };
+
+/**
+ * "Copy Cloud ID" for the "…" menu of a resource. It copies the structured reference and its `/open` permalink as
+ * text: Cloud paste surfaces recognize the resource, and anywhere else the text opens it after sign-in. Without a
+ * configured Cloud URL the menu shows nothing.
+ */
+export const useCloudIdCopy = () => {
+  const locale = useLocale();
+  const t = createMemo(() => cloudIdMessages.resolve([locale()]).t);
+  onMount(() => {
+    if (clipboardModule || !cloudOrigin()) return;
+    const warm = () => void loadClipboard().catch(() => undefined);
+    if (typeof requestIdleCallback === "function") requestIdleCallback(warm, { timeout: 2000 });
+    else setTimeout(warm, 0);
+  });
+
+  const copy = (ref: CloudResourceRef) => {
+    const cloudUrl = cloudOrigin();
+    if (!cloudUrl) return;
+    const failed = () => void toast.error(t().copyFailed);
+    const write = (module: ClipboardModule) => {
+      try {
+        const { cloudResourceClipboard } = module;
+        return cloudResourceClipboard
+          .write({ cloudUrl, ref, fallbackText: cloudResourceClipboard.url(ref, cloudUrl) })
+          .then(() => void toast.success(t().copied), failed);
+      } catch {
+        failed();
+      }
+    };
+    if (clipboardModule) return void write(clipboardModule);
+    // Before the clipboard code loads, copy the permalink alone: WebKit allows a write only while the click is handled.
+    try {
+      void navigator.clipboard.writeText(new URL(cloudResourceHref(ref), cloudUrl).href).then(() => void toast.success(t().copied), failed);
+    } catch {
+      failed();
+    }
+    void loadClipboard().catch(() => undefined);
+  };
+
+  return {
+    available: () => Boolean(cloudOrigin()),
+    copy,
+    /** The last section of a resource's "…" menu; empty without a resource or a configured Cloud URL. */
+    section: (...targets: readonly (CloudResourceRef | CloudIdTarget | null | undefined | false)[]): DropdownItem[] => {
+      if (!cloudOrigin()) return [];
+      const items = targets.flatMap((target) => {
+        if (!target) return [];
+        const { ref, label } = "ref" in target ? target : { ref: target, label: undefined };
+        return [{ label: label ?? t().copy, icon: "ti ti-id", immediate: true, action: () => copy(ref) }];
+      });
+      return items.length > 0 ? [{ items }] : [];
+    },
+  };
+};

package/src/browser/live-websocket.ts

@@ -1,3 +1,6 @@
+/** Transport event; the shell owns its visible recovery without coupling this client to UI. */
+export const APP_ACCESS_REVOKED_EVENT = "cloud:app-access-revoked";
+
 export type LiveWebSocketActivity = "always" | "visible";
 export type LiveWebSocketStatus = "connecting" | "open" | "reconnecting" | "paused" | "closed";
 
@@ -264,6 +267,8 @@ export const createLiveWebSocket = <TMessage>(options: LiveWebSocketOptions<TMes
       socket = null;
       clearConnectDeadline();
       if (disposed || terminated) return;
+      if (event.code === 1008 && event.reason === "app_access_denied")
+        window.dispatchEvent(new CustomEvent(APP_ACCESS_REVOKED_EVENT, { detail: next.url }));
       const closeError = classifyClose({ code: event.code, reason: event.reason.trim() });
       if (closeError) {
         fatal(closeError, { code: event.code, reason: event.reason });

package/src/browser/pwa-drafts.ts

@@ -0,0 +1,57 @@
+/** Plain typed text only. Account and field identifiers belong in keys, never in stored payloads. */
+const PREFIX = "cloud.pwa.draft:";
+const key = (accountId: string, fieldId: string) => `${PREFIX}${encodeURIComponent(accountId)}:${encodeURIComponent(fieldId)}`;
+// A denied/full store must still protect this document from an automatic reload while typing.
+const pending = new Map<string, string>();
+
+export const pwaDrafts = {
+  read(accountId: string, fieldId: string): string | undefined {
+    const id = key(accountId, fieldId);
+    try {
+      return pending.get(id) ?? window.localStorage.getItem(id) ?? undefined;
+    } catch {
+      return pending.get(id);
+    }
+  },
+  /** Call on each input, including empty text. False means the browser could not keep the draft across restarts. */
+  write(accountId: string, fieldId: string, text: string): boolean {
+    const id = key(accountId, fieldId);
+    pending.set(id, text);
+    try {
+      window.localStorage.setItem(id, text);
+      pending.delete(id);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+  /** Call only after saving/sending succeeds, or the person explicitly discards the draft. */
+  remove(accountId: string, fieldId: string): void {
+    const id = key(accountId, fieldId);
+    pending.delete(id);
+    try {
+      window.localStorage.removeItem(id);
+    } catch {}
+  },
+  has(accountId: string): boolean {
+    const prefix = `${PREFIX}${encodeURIComponent(accountId)}:`;
+    if ([...pending.keys()].some((id) => id.startsWith(prefix))) return true;
+    try {
+      const storage = window.localStorage;
+      return Array.from({ length: storage.length }, (_, i) => storage.key(i)).some((id) => id?.startsWith(prefix));
+    } catch {
+      return false;
+    }
+  },
+  /** Sign-out, a removed device, and a new pairing erase every account's app drafts on this browser. */
+  clearAll(): void {
+    pending.clear();
+    try {
+      const storage = window.localStorage;
+      for (let i = storage.length - 1; i >= 0; i--) {
+        const id = storage.key(i);
+        if (id?.startsWith(PREFIX)) storage.removeItem(id);
+      }
+    } catch {}
+  },
+};

package/src/browser/resource-clipboard.ts

@@ -3,7 +3,9 @@ import {
   CLOUD_RESOURCE_CLIPBOARD_MAX_BYTES,
   CLOUD_RESOURCE_CLIPBOARD_MIME_TYPE,
   CLOUD_RESOURCE_CLIPBOARD_WEB_FORMAT,
+  formatCloudResourceUrl,
   parseCloudResourceClipboard,
+  parseCloudResourceUrl,
   serializeCloudResourceClipboard,
 } from "../contracts/resource-clipboard";
 
@@ -65,6 +67,8 @@ export const cloudResourceClipboard = {
   webFormat: CLOUD_RESOURCE_CLIPBOARD_WEB_FORMAT,
   parse: parseCloudResourceClipboard,
   serialize: serializeCloudResourceClipboard,
+  url: formatCloudResourceUrl,
+  parseUrl: parseCloudResourceUrl,
   write: writeCloudResourceClipboard,
   read: readCloudResourceClipboard,
 } as const;

package/src/browser/resource-links.ts

@@ -0,0 +1,52 @@
+import type { CoreApiType } from "../api";
+import { localCloudResourceUrl } from "../contracts/resource-pages";
+import type { ResolvedCloudResourceUrl } from "../contracts/resource-resolution";
+import { createApiClient } from "../server/api-client";
+import { readShellData } from "../ssr/shell-data";
+
+export type { ResolvedCloudResourceUrl } from "../contracts/resource-resolution";
+
+/** Available on Layout and AdminLayout pages; MinimalLayout does not install shell data. */
+export const cloudOrigin = (): string | null => readShellData()?.cloudOrigin ?? null;
+
+/** Recognize one pasted Cloud link. Unsupported, unreadable, and unavailable links all return null. */
+export const resolveCloudUrl = async (text: string, options: { signal?: AbortSignal } = {}): Promise<ResolvedCloudResourceUrl | null> => {
+  const url = text.trim();
+  if (!localCloudResourceUrl(url, cloudOrigin())) return null;
+  try {
+    const response = await createApiClient<CoreApiType>().resources.resolve.$post({ json: { url } }, { init: { signal: options.signal } });
+    if (!response.ok) return null;
+    // Validate only after a successful response; Zod stays out of the initial browser graph.
+    const { ResolvedCloudResourceUrlSchema } = await import("../contracts/resource-resolution");
+    const result = ResolvedCloudResourceUrlSchema.safeParse(await response.json());
+    return result.success ? result.data : null;
+  } catch {
+    return null;
+  }
+};
+
+// Ctrl+Shift+V (Cmd+Shift+V, also with Option, which changes the key's character) asks for plain text; that paste
+// keeps the link as it is.
+let plainPasteAt = -Infinity;
+if (typeof window !== "undefined")
+  window.addEventListener(
+    "keydown",
+    (event) => {
+      if (event.shiftKey && (event.ctrlKey || event.metaKey) && (event.code === "KeyV" || event.key.toLowerCase() === "v"))
+        plainPasteAt = event.timeStamp;
+    },
+    true,
+  );
+
+/**
+ * The Cloud link a paste carries: one absolute URL on this Cloud, as copied from the address bar or "Copy Cloud ID",
+ * and nothing else. Returns null for other text, other origins, and a paste as plain text. Recognize the link with
+ * `resolveCloudUrl()`.
+ */
+export const pastedCloudLink = (event: ClipboardEvent): string | null => {
+  const plain = event.timeStamp - plainPasteAt < 1_000;
+  plainPasteAt = -Infinity;
+  const text = (event.clipboardData?.getData("text/plain") ?? "").trim();
+  if (plain || text.startsWith("/")) return null;
+  return localCloudResourceUrl(text, cloudOrigin()) ? text : null;
+};

package/src/browser/resource-picker.tsx

@@ -4,10 +4,11 @@ import type { CloudResourceRef } from "../contracts";
 import CloudResourceSearch from "./CloudResourceSearch";
 import { resourceSearchDialogOptions } from "./resource-search-dialog";
 import { resourceSearchMessages } from "./resource-search-messages";
+import type { SearchScope } from "./search-bridge";
 
 export type CloudResourcePickerItem = SearchItem;
-/** Narrows the search on the server to one app and, optionally, one of its search tags; shown as the removable chip. */
-export type CloudResourcePickerScope = { appId: string; tag?: string; label: string; icon?: string };
+/** Narrows the server search to an app/tag or resource context; shown as a removable chip. */
+export type CloudResourcePickerScope = SearchScope;
 export type CloudResourcePickerOptions = {
   title?: string;
   placeholder?: string;

package/src/capabilities/calendar-sources.ts

@@ -0,0 +1,302 @@
+import { z } from "zod";
+import {
+  CALENDAR_SOURCE_MAX_RANGE_MS,
+  CALENDAR_SOURCE_PAGE_LIMIT,
+  CalendarEventsDataSchema,
+  CalendarListDataSchema,
+  calendarSourceIssues,
+  projectCalendarDescriptor,
+  projectCalendarItem,
+} from "../contracts/calendar-source";
+import {
+  type CalendarReadResult,
+  type CalendarSelection,
+  type CalendarSourceListEntry,
+  type CalendarSourceSummary,
+  CalendarViewRangeSchema,
+} from "../contracts/calendar-view";
+import { CapabilityAppIdSchema } from "../contracts/capabilities";
+import { type CapabilityCaller, invokeCapabilityWithDataSchema, listCapabilityCatalog } from "./server-invoke";
+import type { CapabilityCatalogApp, CapabilityClientError } from "./types";
+
+export * from "../contracts/calendar-view";
+
+// Interactive read budget: 60 requests, six in flight, 4 MiB of pages.
+const MAX_CALLS = 60;
+const MAX_BYTES = 4 * 1024 * 1024;
+const CONCURRENCY = 6;
+const SelectionSchema = z
+  .array(z.object({ appId: CapabilityAppIdSchema, calendarId: z.string().min(1).max(2048) }).strict())
+  .max(CALENDAR_SOURCE_PAGE_LIMIT);
+
+class ReadStopped extends Error {
+  constructor(
+    readonly state: "pending" | "truncated" | "failed",
+    readonly code: string,
+    readonly retryable = true,
+  ) {
+    super(code);
+  }
+}
+const failure = (error: CapabilityClientError) =>
+  new ReadStopped("failed", error.code, error.status === 429 || error.status >= 500 || error.status === 499);
+
+/** One request only; no identity, catalog or source data survives this session. */
+class ReadSession {
+  private calls = 0;
+  private bytes = 0;
+  private readonly controller = new AbortController();
+  private readonly timer: ReturnType<typeof setTimeout>;
+  private readonly upstream: AbortSignal[];
+  private stop: ReadStopped | undefined;
+  readonly credentials: CapabilityCaller;
+  constructor(credentials: CapabilityCaller, deadline: number, signal?: AbortSignal) {
+    if (!Number.isFinite(deadline)) throw new RangeError("Calendar deadline must be a finite epoch time in milliseconds");
+    this.credentials = { ...credentials, signal: this.controller.signal };
+    if (!credentials.authority) {
+      this.credentials.transport = async (request) => {
+        const response = await (credentials.transport ?? fetch)(request);
+        if (!response.body) return response;
+        const body = response.body.pipeThrough(
+          new TransformStream<Uint8Array, Uint8Array>({
+            transform: (chunk, controller) => {
+              this.addBytes(chunk.byteLength);
+              controller.enqueue(chunk);
+            },
+          }),
+          { signal: this.controller.signal },
+        );
+        return new Response(body, { status: response.status, statusText: response.statusText, headers: response.headers });
+      };
+    }
+    this.upstream = [...new Set([credentials.signal, signal].filter((value): value is AbortSignal => value !== undefined))];
+    for (const upstream of this.upstream) upstream.addEventListener("abort", this.abort, { once: true });
+    this.timer = setTimeout(() => this.halt(new ReadStopped("pending", "CALENDAR_DEADLINE")), Math.max(0, deadline - Date.now()));
+    if (this.upstream.some((upstream) => upstream.aborted)) this.abort();
+    else if (deadline <= Date.now()) this.halt(new ReadStopped("pending", "CALENDAR_DEADLINE"));
+  }
+  private readonly abort = () => this.halt(new ReadStopped("pending", "REQUEST_CANCELLED"));
+  private halt(reason: ReadStopped) {
+    this.stop ??= reason;
+    this.controller.abort();
+  }
+  check() {
+    if (this.stop) throw this.stop;
+  }
+  private addBytes(bytes: number) {
+    this.bytes += bytes;
+    if (this.bytes > MAX_BYTES) {
+      this.halt(new ReadStopped("truncated", "CALENDAR_BYTE_BUDGET"));
+      this.check();
+    }
+  }
+  async page<T>(read: () => Promise<T>): Promise<T> {
+    this.check();
+    if (this.calls >= MAX_CALLS) {
+      this.halt(new ReadStopped("truncated", "CALENDAR_CALL_BUDGET"));
+      this.check();
+    }
+    this.calls++;
+    let onAbort: (() => void) | undefined;
+    try {
+      const cancelled = new Promise<never>((_, reject) => {
+        onAbort = () => reject(this.stop ?? new ReadStopped("pending", "REQUEST_CANCELLED"));
+        this.controller.signal.addEventListener("abort", onAbort, { once: true });
+      });
+      const result = await Promise.race([read(), cancelled]);
+      this.check();
+      // Core in-process authority has no transport body; count its serialized page instead.
+      if (this.credentials.authority) this.addBytes(new TextEncoder().encode(JSON.stringify(result)).byteLength);
+      return result;
+    } finally {
+      if (onAbort) this.controller.signal.removeEventListener("abort", onAbort);
+    }
+  }
+  close() {
+    clearTimeout(this.timer);
+    for (const upstream of this.upstream) upstream.removeEventListener("abort", this.abort);
+  }
+}
+
+const catalog = async (session: ReadSession): Promise<CapabilityCatalogApp[]> => {
+  const apps: CapabilityCatalogApp[] = [];
+  let cursor: string | undefined;
+  const seen = new Set<string>();
+  do {
+    const page = await session.page(() => listCapabilityCatalog({ caller: session.credentials, cursor, limit: 25 }));
+    if (!page.ok) throw failure(page.error);
+    apps.push(...page.data.apps);
+    cursor = page.data.page.hasMore ? page.data.page.nextCursor : undefined;
+    if (cursor && seen.has(cursor)) throw new ReadStopped("failed", "CALENDAR_CURSOR_LOOP", false);
+    if (cursor) seen.add(cursor);
+    if (page.data.page.hasMore && !cursor) throw new ReadStopped("failed", "INVALID_APP_RESPONSE", false);
+  } while (cursor);
+  return apps.filter((app) => app.manifest.calendarSource && calendarSourceIssues(app.manifest).length === 0);
+};
+const workers = async <T>(values: T[], run: (value: T) => Promise<void>) => {
+  let index = 0;
+  await Promise.all(
+    Array.from({ length: Math.min(CONCURRENCY, values.length) }, async () => {
+      while (index < values.length) await run(values[index++]!);
+    }),
+  );
+};
+const stopped = (error: unknown) => (error instanceof ReadStopped ? error : new ReadStopped("failed", "APP_UNAVAILABLE"));
+
+/** Follow calendar pagination for the current caller. A partial list is explicitly failed. */
+export const listCalendarSources = async (
+  credentials: CapabilityCaller,
+  options: { deadline: number; signal?: AbortSignal },
+): Promise<CalendarSourceListEntry[]> => {
+  const session = new ReadSession(credentials, options.deadline, options.signal);
+  try {
+    const apps = await catalog(session);
+    const result = apps.map(
+      (app): CalendarSourceListEntry => ({
+        appId: app.appId,
+        name: app.appName,
+        icon: app.appIcon ?? null,
+        state: "ok",
+        error: null,
+        calendars: [],
+      }),
+    );
+    await workers(apps, async (app) => {
+      const source = result.find((source) => source.appId === app.appId)!;
+      try {
+        let cursor: string | undefined;
+        const seen = new Set<string>();
+        const ids = new Set<string>();
+        do {
+          const page = await session.page(() =>
+            invokeCapabilityWithDataSchema(
+              {
+                appId: app.appId,
+                capabilityId: app.manifest.calendarSource!.calendars,
+                kind: "query",
+                input: { limit: CALENDAR_SOURCE_PAGE_LIMIT, ...(cursor ? { cursor } : {}) },
+              },
+              CalendarListDataSchema,
+              session.credentials,
+            ),
+          );
+          if (!page.ok) throw failure(page.error);
+          for (const entry of page.data.data.items)
+            if (!ids.has(entry.id)) {
+              ids.add(entry.id);
+              if (source.calendars.length < CALENDAR_SOURCE_PAGE_LIMIT) source.calendars.push(projectCalendarDescriptor(entry));
+            }
+          cursor = page.data.data.next ?? undefined;
+          if (ids.size > CALENDAR_SOURCE_PAGE_LIMIT) throw new ReadStopped("truncated", "CALENDAR_CALENDAR_BUDGET");
+          if (cursor && seen.has(cursor)) throw new ReadStopped("failed", "CALENDAR_CURSOR_LOOP", false);
+          if (cursor) seen.add(cursor);
+        } while (cursor);
+      } catch (error) {
+        const reason = stopped(error);
+        source.state = "failed";
+        source.error = { code: reason.code, retryable: reason.retryable };
+      }
+    });
+    return result;
+  } finally {
+    session.close();
+  }
+};
+
+/** Deadline is an absolute epoch millisecond time. onSource receives each source's final progress state. */
+export const readCalendarEvents = async (options: {
+  credentials: CapabilityCaller;
+  calendars: CalendarSelection[];
+  from: string;
+  to: string;
+  signal?: AbortSignal;
+  deadline: number;
+  onSource?: (source: CalendarSourceSummary) => void;
+}): Promise<CalendarReadResult> => {
+  const calendars = SelectionSchema.parse(options.calendars);
+  const { from, to } = CalendarViewRangeSchema.parse({ from: options.from, to: options.to });
+  const grouped = new Map<string, Set<string>>();
+  for (const { appId, calendarId } of calendars) {
+    const ids = grouped.get(appId) ?? new Set<string>();
+    ids.add(calendarId);
+    grouped.set(appId, ids);
+  }
+  const result: CalendarReadResult = { items: [], sources: [...grouped.keys()].map((appId) => ({ appId, state: "pending", error: null })) };
+  if (!calendars.length) return result;
+  const session = new ReadSession(options.credentials, options.deadline, options.signal);
+  const dedupe = new Set<string>();
+  try {
+    let apps: CapabilityCatalogApp[];
+    try {
+      apps = await catalog(session);
+    } catch (error) {
+      const reason = stopped(error);
+      for (const source of result.sources) {
+        source.state = reason.state;
+        source.error = { code: reason.code, retryable: reason.retryable };
+        options.onSource?.({ ...source });
+      }
+      return result;
+    }
+    await workers(result.sources, async (source) => {
+      try {
+        session.check();
+        const app = apps.find((app) => app.appId === source.appId);
+        if (!app) throw new ReadStopped("failed", "CAPABILITY_NOT_FOUND", false);
+        for (let start = Date.parse(from); start < Date.parse(to); start += CALENDAR_SOURCE_MAX_RANGE_MS) {
+          const end = Math.min(start + CALENDAR_SOURCE_MAX_RANGE_MS, Date.parse(to));
+          let cursor: string | undefined;
+          const seen = new Set<string>();
+          do {
+            const page = await session.page(() =>
+              invokeCapabilityWithDataSchema(
+                {
+                  appId: source.appId,
+                  capabilityId: app.manifest.calendarSource!.events,
+                  kind: "query",
+                  input: {
+                    calendarIds: [...grouped.get(source.appId)!],
+                    from: new Date(start).toISOString(),
+                    to: new Date(end).toISOString(),
+                    limit: CALENDAR_SOURCE_PAGE_LIMIT,
+                    ...(cursor ? { cursor } : {}),
+                  },
+                },
+                CalendarEventsDataSchema,
+                session.credentials,
+              ),
+            );
+            if (!page.ok) throw failure(page.error);
+            for (const item of page.data.data.items) {
+              if (!grouped.get(source.appId)!.has(item.calendarId)) continue;
+              const key = JSON.stringify([source.appId, item.calendarId, item.id]);
+              if (dedupe.has(key)) continue;
+              dedupe.add(key);
+              result.items.push({ ...projectCalendarItem(item), appId: source.appId });
+            }
+            cursor = page.data.data.next ?? undefined;
+            if (cursor && seen.has(cursor)) throw new ReadStopped("failed", "CALENDAR_CURSOR_LOOP", false);
+            if (cursor) seen.add(cursor);
+          } while (cursor);
+        }
+        source.state = "ok";
+      } catch (error) {
+        const reason = stopped(error);
+        source.state = reason.state;
+        source.error = { code: reason.code, retryable: reason.retryable };
+      }
+      options.onSource?.({ ...source });
+    });
+    const point = (item: CalendarReadResult["items"][number]) => {
+      const time = item.type === "deadline" ? (item.due.kind === "date" ? item.due.date : item.due.at) : item.time.start;
+      return Date.parse(time);
+    };
+    result.items.sort(
+      (a, b) =>
+        point(a) - point(b) || a.appId.localeCompare(b.appId) || a.calendarId.localeCompare(b.calendarId) || a.id.localeCompare(b.id),
+    );
+    return result;
+  } finally {
+    session.close();
+  }
+};