gloomberb 0.12.0 → 0.13.2

package/README.md

@@ -137,6 +137,8 @@ Open command mode with `Ctrl+P`, then type a command. Press `` ` `` to open tick
 
 Use **New Portfolio** or **Add Broker Account** to connect a broker. Gloomberb can import positions from Interactive Brokers, Public, Robinhood, and SimpleFIN.
 
+Each broker is a plugin with its own repository, installed on first launch and updatable on its own. Manage them from the plugin directory, or with `gloomberb install gloom-sh/gloomberb-public` and friends.
+
 - Robinhood opens a browser sign-in page. Gloomberb uses only the read-only account and equity-position tools from the Robinhood Trading MCP server.
 - Public needs an API secret from Public API settings. Gloomberb creates a short-lived access token and uses only the account and portfolio endpoints.
 - SimpleFIN needs a one-time setup token from SimpleFIN Bridge. Gloomberb exchanges the token and imports only accounts that contain holdings.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gloomberb",
-  "version": "0.12.0",
+  "version": "0.13.2",
   "packageManager": "bun@1.3.11",
   "description": "Market research and portfolio tracker for the terminal",
   "module": "src/index.tsx",
@@ -94,7 +94,6 @@
   "dependencies": {
     "@earendil-works/pi-agent-core": "0.81.1",
     "@earendil-works/pi-ai": "0.81.1",
-    "@modelcontextprotocol/sdk": "^1.30.0",
     "@opentui/core": "^0.3.2",
     "@opentui/react": "^0.3.2",
     "@stoqey/ib": "^1.5.6",

package/src/api-client/auth.ts

@@ -1,3 +1,4 @@
+import { getCurrentPluginTarget } from "../plugins/current-target";
 import { ApiRequestError, isHardSessionInvalidMessage } from "./errors";
 import type {
   AccountProfile,
@@ -151,7 +152,7 @@ export class CloudAuthApi {
   async sendVerification(): Promise<CloudVerificationResponse> {
     return this.options.request<CloudVerificationResponse>("/cloud/auth/send-verification", {
       method: "POST",
-      body: JSON.stringify({}),
+      body: JSON.stringify({ returnTo: getCurrentPluginTarget() === "web" ? location.href : undefined }),
     });
   }
 

package/src/api-client/index.test.ts

@@ -264,6 +264,40 @@ describe("apiClient auth cookies", () => {
     ]);
   });
 
+  test("ignores a stale response cookie after the session credential changes", async () => {
+    let releaseResponse: (() => void) | null = null;
+    let markRequestStarted: (() => void) | null = null;
+    const requestStarted = new Promise<void>((resolve) => {
+      markRequestStarted = resolve;
+    });
+
+    apiClient.setSessionToken("old-session.value");
+    setCloudApiFetchTransport(async () => {
+      markRequestStarted?.();
+      await new Promise<void>((resolve) => {
+        releaseResponse = resolve;
+      });
+      return createResponse({
+        channels: [],
+        onlineCount: 0,
+        channelStates: [],
+        notifications: [],
+      }, {
+        cookies: [
+          "__Secure-gloomberb.session_token=old-session.value; Path=/; HttpOnly; Secure; SameSite=None",
+        ],
+      });
+    });
+
+    const staleRequest = apiClient.getChatState();
+    await requestStarted;
+    apiClient.setSessionToken("new-session.value");
+    releaseResponse?.();
+    await staleRequest;
+
+    expect(apiClient.getSessionToken()).toBe("new-session.value");
+  });
+
   test("uses an installed cloud API fetch transport for auth cookie capture", async () => {
     const seenCookies: Array<string | null> = [];
     globalThis.fetch = mockFetch(async () => {

package/src/api-client/index.ts

@@ -362,8 +362,16 @@ class GloomApiClient {
   }
 
   /** Creates a Stripe checkout session for Cloud Pro; the URL opens in a browser. */
-  async createCloudCheckout(): Promise<{ url: string }> {
-    return this.request<{ url: string }>("/stripe/checkout", { method: "POST", body: JSON.stringify({}) });
+  async createCloudCheckout(returnTo?: string): Promise<{ url: string }> {
+    return this.request<{ url: string }>("/stripe/checkout", { method: "POST", body: JSON.stringify({ returnTo }) });
+  }
+
+  async recordResearchActivity(payload: {
+    event: import("./research-activity").ResearchActivity; eventId: string;
+    surface: "web" | "desktop" | "tui" | "cli"; anonymousId?: string;
+    attribution?: Record<string, string>; feature?: import("./research-activity").ResearchFeature;
+  }): Promise<void> {
+    await this.request("/activity/research", { method: "POST", body: JSON.stringify(payload) });
   }
 
   /** Stores a verified user's public terminal snapshot or pane handoff. */

package/src/api-client/request.ts

@@ -141,6 +141,7 @@ export class CloudApiRequestTransport {
       headers.set("Content-Type", "application/json");
     }
     this.setSessionCookieHeader(headers);
+    const sessionTokenAtRequestStart = this.sessionToken;
     headers.set("Origin", this.baseUrl);
 
     const operation = `${options?.method ?? "GET"} ${path.split("?")[0]}`;
@@ -151,7 +152,9 @@ export class CloudApiRequestTransport {
         credentials: "include",
       });
       throwIfRequestAborted(options?.signal);
-      this.extractSessionCookie(res);
+      if (this.sessionToken === sessionTokenAtRequestStart) {
+        this.extractSessionCookie(res);
+      }
       const text = await res.text();
       throwIfRequestAborted(options?.signal);
 

package/src/api-client/research-activity.ts

@@ -0,0 +1,61 @@
+import { apiClient } from "./index";
+import { getCurrentPluginTarget } from "../plugins/current-target";
+
+export type ResearchActivity = "workspace_opened" | "research_viewed" | "ticker_saved" | "pro_feature_used" | "upgrade_intent";
+export type ResearchFeature = "overview" | "chart" | "financials" | "news" | "transcripts" | "search" | "research";
+const sent = new Set<string>();
+let anonymousId: string | undefined;
+let attribution: Record<string, string> = {};
+
+/** Hosted web analytics only. Native local use never creates an identifier. */
+export function initializeBrowserResearchActivity(): void {
+  try {
+    if (navigator.doNotTrack === "1" || (navigator as Navigator & { globalPrivacyControl?: boolean }).globalPrivacyControl) return;
+    const url = new URL(location.href);
+    const incoming = url.searchParams.get("_gloom");
+    const stored = localStorage.getItem("gloomberb.web.anonymous-id");
+    anonymousId = [incoming, stored].find((value) => value && /^[a-f0-9-]{36}$/.test(value)) ?? crypto.randomUUID();
+    localStorage.setItem("gloomberb.web.anonymous-id", anonymousId);
+    const keys = ["utm_source", "utm_medium", "utm_campaign", "utm_content", "utm_term", "twclid"];
+    const saved = JSON.parse(localStorage.getItem("gloomberb.web.attribution") ?? "{}");
+    const age = Date.now() - Date.parse(saved?.last_touch_at ?? "");
+    attribution = Number.isFinite(age) && age >= 0 && age < 30 * 24 * 60 * 60 * 1000 ? saved : {};
+    if (keys.some((key) => url.searchParams.has(key))) {
+      // A new campaign replaces the old click id instead of inheriting it.
+      attribution = { last_touch_at: new Date().toISOString() };
+      for (const key of keys) {
+        const value = url.searchParams.get(key);
+        if (value) attribution[key] = value.slice(0, 300);
+      }
+    }
+    localStorage.setItem("gloomberb.web.attribution", JSON.stringify(attribution));
+    url.searchParams.delete("_gloom");
+    history.replaceState(history.state, "", url.href);
+  } catch { /* Private browsing must still work. */ }
+}
+
+/** Counts milestones once per feature/session/account, never their content. */
+export function recordResearchActivity(event: ResearchActivity, feature?: ResearchFeature): void {
+  const target = getCurrentPluginTarget();
+  const user = apiClient.getCurrentUser();
+  if (target === "web" ? !anonymousId : !user) return;
+  const key = `${user?.id ?? "guest"}:${event}:${feature ?? ""}`;
+  if (sent.has(key)) return;
+  sent.add(key);
+  if (event !== "workspace_opened") recordResearchActivity("workspace_opened");
+  void apiClient.recordResearchActivity({ event, eventId: crypto.randomUUID(),
+    surface: target === "desktop" ? "desktop" : target,
+    anonymousId: target === "web" ? anonymousId : undefined,
+    attribution: target === "web" ? attribution : undefined, feature,
+  }).catch(() => { sent.delete(key); });
+}
+
+export function researchUpgradeUrl(returnTo?: string): string {
+  const url = new URL("https://gloom.sh/cloud?upgrade=pro");
+  if (returnTo) url.searchParams.set("returnTo", returnTo);
+  if (anonymousId) url.searchParams.set("_gloom", anonymousId);
+  for (const [key, value] of Object.entries(attribution)) {
+    if (/^(utm_(source|medium|campaign|content|term)|twclid)$/.test(key)) url.searchParams.set(key, value);
+  }
+  return url.href;
+}

package/src/api-client/types.ts

@@ -518,7 +518,8 @@ export interface CloudTranscriptTurnPayload {
   company?: string;
   text: string;
   isQa: boolean;
-  startSeconds: number;
+  /** Offset into the recording; null when the company published the transcript as a document. */
+  startSeconds: number | null;
 }
 
 export interface CloudTranscriptParticipantPayload {

package/src/cli/commands/plugins.ts

@@ -1,7 +1,7 @@
 import { join } from "path";
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync } from "fs";
 import { execFileSync } from "child_process";
-import { getPluginsDir } from "../../plugins/loader";
+import { getPluginsDir, isPluginDirectory } from "../../plugins/loader";
 import { linkHostPackages } from "../../plugins/host-link";
 import {
   cliStyles,
@@ -149,7 +149,7 @@ export async function updatePlugins(name?: string) {
   const dirs = name
     ? [validatePluginDirectoryName(name)]
     : readdirSync(PLUGINS_DIR, { withFileTypes: true })
-        .filter((entry) => entry.isDirectory())
+        .filter((entry) => entry.isDirectory() && isPluginDirectory(entry.name))
         .map((entry) => entry.name);
 
   if (dirs.length === 0) {
@@ -179,7 +179,8 @@ export async function updatePlugins(name?: string) {
 
 export function listPlugins() {
   ensurePluginsDir();
-  const entries = readdirSync(PLUGINS_DIR, { withFileTypes: true }).filter((entry) => entry.isDirectory());
+  const entries = readdirSync(PLUGINS_DIR, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && isPluginDirectory(entry.name));
 
   if (entries.length === 0) {
     console.log(cliStyles.muted("No plugins installed."));

package/src/cli/desktop-pane-shot.ts

@@ -3,7 +3,8 @@ import { tmpdir } from "os";
 import { join, resolve, sep } from "path";
 import type { AppConfig } from "../types/config";
 import type { ResolvedSeries } from "../time-series/types";
-import type { OptionsChain, TickerFinancials } from "../types/financials";
+import type { OptionsChain, PricePoint, TickerFinancials } from "../types/financials";
+import type { ManualChartResolution } from "../time-series/resolution";
 import type { TickerRecord } from "../types/ticker";
 import type { PaneRuntimeState } from "../core/state/app/state";
 import type { RemoteUiNodeSnapshot } from "../remote/types";
@@ -14,6 +15,19 @@ import {
   writeElectrobunViewPage,
 } from "../renderers/electrobun/view/build-assets";
 
+export interface DesktopPaneShotIntradayHistory {
+  symbol: string;
+  exchange: string;
+  rangePreset: "1D" | "1W";
+  resolution: ManualChartResolution;
+  requestedSession: string | null;
+  sessionDates: string[];
+  points: PricePoint[];
+  start: string | null;
+  end: string | null;
+  unavailableReason: string | null;
+}
+
 export interface DesktopPaneShotPayload {
   config: AppConfig;
   paneId: string;
@@ -27,6 +41,7 @@ export interface DesktopPaneShotPayload {
   watermark?: string | null;
   tickers: TickerRecord[];
   financials: Array<[string, TickerFinancials]>;
+  intradayHistories: DesktopPaneShotIntradayHistory[];
   optionsChains: Array<[string, OptionsChain]>;
   fredSeries: Array<[string, FredSeriesCacheEntry]>;
   valuationSeries: Array<[string, DatedObservation[]]>;
@@ -58,6 +73,8 @@ export interface DesktopPaneShotRenderedRow {
 export interface DesktopPaneShotRenderResult {
   visibleText: string;
   rows: DesktopPaneShotRenderedRow[];
+  truncated: boolean;
+  truncationReasons: string[];
   loadingStateDetected: boolean;
   errorStateDetected: boolean;
   errorStateMarkers: string[];
@@ -98,6 +115,7 @@ export async function renderDesktopPaneScreenshot(
   payload: DesktopPaneShotPayload,
   outputPath: string,
   apiProxy: DesktopPaneShotApiProxy,
+  options: { captureImage?: boolean } = {},
 ): Promise<DesktopPaneShotRenderResult> {
   const tempDir = await mkdtemp(join(tmpdir(), "gloom-pane-shot-"));
   let server: ReturnType<typeof Bun.serve> | null = null;
@@ -115,6 +133,7 @@ export async function renderDesktopPaneScreenshot(
       heightPx: payload.heightPx,
       deviceScaleFactor: payload.deviceScaleFactor ?? DEFAULT_DEVICE_SCALE_FACTOR,
       userDataDir: join(tempDir, "chrome-profile"),
+      captureImage: options.captureImage !== false,
     });
   } finally {
     server?.stop(true);
@@ -296,6 +315,7 @@ async function capturePageScreenshot({
   heightPx,
   deviceScaleFactor,
   userDataDir,
+  captureImage,
 }: {
   chrome: string;
   url: string;
@@ -304,6 +324,7 @@ async function capturePageScreenshot({
   heightPx: number;
   deviceScaleFactor: number;
   userDataDir: string;
+  captureImage: boolean;
 }): Promise<DesktopPaneShotRenderResult> {
   await mkdir(userDataDir, { recursive: true });
   const port = 43000 + Math.floor(Math.random() * 10000);
@@ -344,13 +365,15 @@ async function capturePageScreenshot({
     });
     await waitForShotReady(session);
     const rendered = await readRenderedPaneState(session);
-    const screenshot = await session.send("Page.captureScreenshot", {
-      format: "png",
-      fromSurface: true,
-      captureBeyondViewport: false,
-    }) as { data?: string };
-    if (!screenshot.data) throw new Error("Chrome did not return screenshot data.");
-    await writeFile(outputPath, Uint8Array.from(Buffer.from(screenshot.data, "base64")));
+    if (captureImage) {
+      const screenshot = await session.send("Page.captureScreenshot", {
+        format: "png",
+        fromSurface: true,
+        captureBeyondViewport: false,
+      }) as { data?: string };
+      if (!screenshot.data) throw new Error("Chrome did not return screenshot data.");
+      await writeFile(outputPath, Uint8Array.from(Buffer.from(screenshot.data, "base64")));
+    }
     return rendered;
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
@@ -373,6 +396,7 @@ const ERROR_STATE_PATTERNS = [
   /\bCould not load\b/gi,
   /\bSign in to\b/gi,
   /\bVerify your email\b/gi,
+  /\brequires signup and email verification\b/gi,
   /\bpart of Gloom Cloud Pro\b/gi,
   /\bCloud API request failed\b/gi,
 ];
@@ -416,6 +440,25 @@ async function readRenderedPaneState(session: CdpSession): Promise<DesktopPaneSh
       };
       const semanticTables = semanticUi.filter((node) => node && node.role === "table");
       const rows = [];
+      const truncationReasons = new Set();
+      const markScrollTruncation = (element) => {
+        if (!(element instanceof HTMLElement) || !isVisible(element)) return;
+        if (
+          element.getAttribute("data-gloom-scrollbar-y") === "visible"
+          || element.scrollHeight > element.clientHeight + 1
+        ) {
+          truncationReasons.add("rows extend below the rendered viewport");
+        }
+        if (
+          element.getAttribute("data-gloom-scrollbar-x") === "visible"
+          || element.scrollWidth > element.clientWidth + 1
+        ) {
+          truncationReasons.add("columns extend beyond the rendered viewport");
+        }
+      };
+      [...root.querySelectorAll(
+        '[data-gloom-scrollbar-x="visible"], [data-gloom-scrollbar-y="visible"], [data-gloom-role="data-table-body-scroll"]',
+      )].forEach(markScrollTruncation);
       [...root.querySelectorAll('[data-gloom-role="data-table"]')]
         .filter(isVisible)
         .forEach((table, tableIndex) => {
@@ -433,12 +476,24 @@ async function readRenderedPaneState(session: CdpSession): Promise<DesktopPaneSh
             const semanticRow = semanticRows[rowIndex] || {};
             const cells = values.map((cell, cellIndex) => {
               const semanticColumn = semanticColumns[cellIndex] || {};
+              const text = normalize(cell.innerText || cell.textContent);
+              const textNodes = [cell, ...cell.querySelectorAll('*')];
+              if (
+                /\\u2026|\\.\\.\\./.test(text)
+                || textNodes.some((node) => (
+                  node instanceof HTMLElement
+                  && isVisible(node)
+                  && node.scrollWidth > node.clientWidth + 1
+                ))
+              ) {
+                truncationReasons.add("one or more cells are visibly clipped");
+              }
               return {
                 ...(typeof semanticColumn.id === "string" ? { columnId: semanticColumn.id } : {}),
                 columnLabel: typeof semanticColumn.label === "string"
                   ? semanticColumn.label
                   : headers[cellIndex] || (values.length === 1 ? "Row" : String(cellIndex + 1)),
-                text: normalize(cell.innerText || cell.textContent),
+                text,
               };
             }).filter((cell) => cell.text.length > 0);
             if (cells.length === 0) return;
@@ -472,6 +527,8 @@ async function readRenderedPaneState(session: CdpSession): Promise<DesktopPaneSh
         errorStateDetected: root.querySelector('[data-gloom-status="error"]') !== null,
         emptyStateDetected: root.querySelector('[data-gloom-status="empty"]') !== null,
         rows,
+        truncated: truncationReasons.size > 0,
+        truncationReasons: [...truncationReasons],
         semanticUi,
       };
     })()`,
@@ -485,6 +542,8 @@ async function readRenderedPaneState(session: CdpSession): Promise<DesktopPaneSh
         errorStateDetected?: boolean;
         emptyStateDetected?: boolean;
         rows?: DesktopPaneShotRenderedRow[];
+        truncated?: boolean;
+        truncationReasons?: string[];
         semanticUi?: RemoteUiNodeSnapshot[];
       };
     };
@@ -495,9 +554,19 @@ async function readRenderedPaneState(session: CdpSession): Promise<DesktopPaneSh
   const loadingStateMarkers = stateMarkers(visibleText, LOADING_STATE_PATTERNS);
   const errorStateMarkers = stateMarkers(visibleText, ERROR_STATE_PATTERNS);
   const emptyStateMarkers = stateMarkers(visibleText, EMPTY_STATE_PATTERNS);
+  const rows = Array.isArray(value?.rows) ? value.rows : [];
+  const textShowsEllipsis = rows.some((row) => row.cells.some((cell) => /\u2026|\.\.\./.test(cell.text)));
+  const truncationReasons = Array.isArray(value?.truncationReasons)
+    ? value.truncationReasons.filter((reason): reason is string => typeof reason === "string")
+    : [];
+  if (textShowsEllipsis && !truncationReasons.includes("one or more cells are visibly clipped")) {
+    truncationReasons.push("one or more cells are visibly clipped");
+  }
   return {
     visibleText,
-    rows: Array.isArray(value?.rows) ? value.rows : [],
+    rows,
+    truncated: value?.truncated === true || textShowsEllipsis,
+    truncationReasons,
     loadingStateDetected: value?.loadingStateDetected === true || loadingStateMarkers.length > 0,
     errorStateDetected: value?.errorStateDetected === true || errorStateMarkers.length > 0,
     errorStateMarkers,

package/src/cli/pane-functions/capabilities.ts

@@ -9,8 +9,8 @@ import type {
   PaneTemplateDef,
 } from "../../types/plugin";
 
-export type PaneFunctionReadiness = "ready" | "partial" | "unsupported";
-export type PaneFunctionScreenshotReadiness = PaneFunctionReadiness | "live-dom";
+export type PaneFunctionReadiness = "ready" | "partial" | "live-dom" | "unsupported";
+export type PaneFunctionScreenshotReadiness = PaneFunctionReadiness;
 export type PaneFunctionTickerCardinality = "none" | "one" | "one-or-more" | "two-or-more" | "one-or-two";
 export type PaneFunctionOptionType = HeadlessPaneOptionType;
 export type PaneFunctionOptionValue = HeadlessPaneOptionValue;
@@ -376,28 +376,80 @@ const CAPABILITIES: Record<string, PaneFunctionCapability> = {
     intents: ["chart intraday security prices"],
     outputKind: "price-history",
     reportReadiness: "ready",
-    screenshotReadiness: "partial",
+    screenshotReadiness: "ready",
     dataRequirements: ["intraday price history"],
-    limitations: ["Intraday availability depends on the selected market-data provider."],
-    options: [],
+    limitations: ["Intraday availability and historical retention depend on the selected market-data provider."],
+    options: [
+      {
+        key: "rangePreset",
+        description: "Session window. 1D selects the latest session and 1W selects the latest five sessions.",
+        type: "enum",
+        aliases: ["range"],
+        values: RANGE_VALUES.filter(({ value }) => value === "1D" || value === "1W"),
+        defaultValue: "1D",
+      },
+      {
+        key: "chartResolution",
+        description: "Intraday sampling interval. Auto uses 1m for 1D and 5m for 1W.",
+        type: "enum",
+        aliases: ["resolution"],
+        values: ["auto", "5m", "15m", "1h"].map((value) => ({ value })),
+        defaultValue: "auto",
+      },
+      {
+        key: "session",
+        description: "Specific exchange-local session in YYYY-MM-DD form. Overrides the session window.",
+        type: "string",
+      },
+    ],
   },
 };
 
-const UNSUPPORTED_CAPABILITY: PaneFunctionCapability = {
-  id: "unverified-pane",
-  botSafe: false,
-  tickerCardinality: "none",
-  aliases: [],
-  intents: [],
-  outputKind: "pane",
-  reportReadiness: "unsupported",
-  screenshotReadiness: "live-dom",
-  dataRequirements: [],
-  limitations: [
-    "Reports are not verified for automation. Screenshots render live and derive evidence from visible DOM rows.",
-  ],
-  options: [],
-};
+const NON_DATA_PANE_IDS = new Set([
+  "account-management",
+  "brokers",
+  "changelog",
+  "chat",
+  "connections",
+  "data-catalog",
+  "debug",
+  "help",
+  "ibkr-trading",
+  "layout-marketplace",
+  "local-agent-workspace",
+  "macro-tv",
+  "plugin-marketplace",
+  "world-venue-map",
+]);
+
+const RENDERED_VIEW_LIMITATION =
+  "Reports contain only values exposed by the rendered view and may omit clipped or off-screen data.";
+
+function fallbackCapability(
+  template: PaneTemplateDef | undefined,
+  pane: PaneDef,
+): PaneFunctionCapability {
+  const dataPane = isDataPaneForDomFallback(pane);
+  return {
+    id: template?.id ?? pane.id,
+    botSafe: false,
+    tickerCardinality: "none",
+    aliases: [],
+    intents: [],
+    outputKind: dataPane ? "rendered-view" : "pane",
+    reportReadiness: dataPane ? "live-dom" : "unsupported",
+    screenshotReadiness: "live-dom",
+    dataRequirements: [],
+    limitations: [dataPane
+      ? RENDERED_VIEW_LIMITATION
+      : "This pane is an interactive surface and does not expose a data report."],
+    options: [],
+  };
+}
+
+export function isDataPaneForDomFallback(pane: Pick<PaneDef, "id">): boolean {
+  return !NON_DATA_PANE_IDS.has(pane.id);
+}
 
 function optionToken(value: string): string {
   return value.trim().toLowerCase().replace(/[\s_.-]+/g, "");
@@ -431,13 +483,14 @@ export function getPaneFunctionCapability(
   template: PaneTemplateDef | undefined,
   pane: PaneDef,
 ): PaneFunctionCapability {
-  const existing = template ? CAPABILITIES[template.id] ?? UNSUPPORTED_CAPABILITY : UNSUPPORTED_CAPABILITY;
+  const fallback = fallbackCapability(template, pane);
+  const existing = template ? CAPABILITIES[template.id] ?? fallback : fallback;
   const headless = getHeadlessPaneDefinition(template, pane);
   if (!headless) return existing;
 
-  const hasExistingCapability = existing !== UNSUPPORTED_CAPABILITY;
+  const hasExistingCapability = existing !== fallback;
   return {
-    ...(hasExistingCapability ? existing : UNSUPPORTED_CAPABILITY),
+    ...(hasExistingCapability ? existing : fallback),
     id: hasExistingCapability ? existing.id : template?.id ?? pane.id,
     botSafe: true,
     tickerCardinality: headlessTickerCardinality(headless.argument),

package/src/cli/pane-functions/cloud-session.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, test } from "bun:test";
+import { apiClient } from "../../api-client";
+import type { MarketContext } from "../types";
+import {
+  resolvePersistedCloudSessionToken,
+  withPersistedCloudSession,
+} from "./cloud-session";
+
+function contextWithSession(
+  key: string,
+  sessionToken: string,
+): Pick<MarketContext, "persistence"> {
+  return {
+    persistence: {
+      pluginState: {
+        get: (_pluginId: string, candidate: string) => candidate === key
+          ? { value: { sessionToken }, schemaVersion: 1, updatedAt: 1 }
+          : null,
+      },
+    },
+  } as Pick<MarketContext, "persistence">;
+}
+
+describe("pane function Cloud session", () => {
+  test("restores the current and legacy persisted session keys", () => {
+    expect(resolvePersistedCloudSessionToken(
+      contextWithSession("resume:session", "current-session"),
+    )).toBe("current-session");
+    expect(resolvePersistedCloudSessionToken(
+      contextWithSession("session", "legacy-session"),
+    )).toBe("legacy-session");
+  });
+
+  test("scopes the persisted session to one report load", async () => {
+    const initial = apiClient.getSessionToken();
+    apiClient.setSessionToken("previous-session");
+    try {
+      let activeSession: string | null = null;
+      const result = await withPersistedCloudSession(
+        contextWithSession("resume:session", "report-session"),
+        async () => {
+          activeSession = apiClient.getSessionToken();
+          return 42;
+        },
+      );
+
+      expect(result).toBe(42);
+      expect(activeSession).toBe("report-session");
+      expect(apiClient.getSessionToken()).toBe("previous-session");
+    } finally {
+      apiClient.setSessionToken(initial);
+    }
+  });
+});

package/src/cli/pane-functions/cloud-session.ts

@@ -0,0 +1,38 @@
+import { apiClient } from "../../api-client";
+import type { MarketContext } from "../types";
+
+const CLOUD_PLUGIN_ID = "gloomberb-cloud";
+const CLOUD_SESSION_KEYS = ["resume:session", "session"] as const;
+
+interface PersistedCloudSession {
+  sessionToken?: unknown;
+}
+
+export function resolvePersistedCloudSessionToken(
+  context: Pick<MarketContext, "persistence">,
+): string | null {
+  for (const key of CLOUD_SESSION_KEYS) {
+    const value = context.persistence.pluginState.get<PersistedCloudSession>(
+      CLOUD_PLUGIN_ID,
+      key,
+      1,
+    )?.value;
+    if (typeof value?.sessionToken === "string" && value.sessionToken.length > 0) {
+      return value.sessionToken;
+    }
+  }
+  return null;
+}
+
+export async function withPersistedCloudSession<T>(
+  context: Pick<MarketContext, "persistence">,
+  run: () => Promise<T>,
+): Promise<T> {
+  const previousSessionToken = apiClient.getSessionToken();
+  apiClient.setSessionToken(resolvePersistedCloudSessionToken(context));
+  try {
+    return await run();
+  } finally {
+    apiClient.setSessionToken(previousSessionToken);
+  }
+}