gloomberb 0.16.3 → 0.16.5

package/src/api-client/index.ts

@@ -59,7 +59,7 @@ export type {
 /** Server-side caps for `/assist/command`; enforced here so a 422 is never sent. */
 const ASSIST_QUERY_MAX_LENGTH = 200;
 const ASSIST_COMMAND_LIMIT = 150;
-const ASSIST_ARG_OPTION_LIMIT = 40;
+const ASSIST_ARG_OPTION_LIMIT = 64;
 const ASSIST_ARG_OPTION_VALUE_MAX_LENGTH = 40;
 const ASSIST_ARG_OPTION_LABEL_MAX_LENGTH = 60;
 const ASSIST_REQUEST_TIMEOUT_MS = 6_000;
@@ -425,6 +425,8 @@ class GloomApiClient {
   async recordExperimentExposure(payload: {
     eventId: string; surface: "web" | "desktop" | "tui" | "cli"; anonymousId?: string;
     attribution?: Record<string, string>; experiment: string; variant?: string;
+    /** Where the experiment showed, by a content-free id like an upgrade placement. */
+    placement?: string;
   }, signal?: AbortSignal): Promise<import("./web-experiments").ExperimentAnswer> {
     return this.request("/activity/research", {
       method: "POST",
@@ -441,6 +443,7 @@ class GloomApiClient {
   getCalendarFeed = this.auth.getCalendarFeed.bind(this.auth);
   ensureCalendarFeed = this.auth.ensureCalendarFeed.bind(this.auth);
   rotateCalendarFeed = this.auth.rotateCalendarFeed.bind(this.auth);
+  createMcpKey = this.auth.createMcpKey.bind(this.auth);
 
   async getSyncSnapshot(): Promise<CloudSyncSnapshotResponse> {
     return this.request<CloudSyncSnapshotResponse>("/sync/snapshot", { method: "GET" });
@@ -643,6 +646,9 @@ class GloomApiClient {
   connectChannel = this.chat.connectChannel.bind(this.chat);
   subscribeChatNotifications = this.chat.subscribeNotifications.bind(this.chat);
   subscribeChatPresence = this.chat.subscribePresence.bind(this.chat);
+  getChatDiscordLink = this.chat.getDiscordLink.bind(this.chat);
+  unlinkChatDiscord = this.chat.unlinkDiscord.bind(this.chat);
+  setChatDiscordMirror = this.chat.setDiscordMirror.bind(this.chat);
   subscribeQuotes = this.socket.subscribeQuotes.bind(this.socket);
 
   listTeams = this.teams.listTeams.bind(this.teams);
@@ -668,6 +674,10 @@ class GloomApiClient {
   subscribeTeamUpdates = this.teams.subscribeTeamUpdates.bind(this.teams);
   subscribeTeamNotifications = this.teams.subscribeTeamNotifications.bind(this.teams);
   subscribeCloudEvent = this.teams.subscribeCloudEvent.bind(this.teams);
+  /** The Cloud socket's own lifecycle and frames, for protocols layered on it (the terminal relay). */
+  subscribeSocketConnection = this.socket.subscribeConnection.bind(this.socket);
+  sendSocketFrame = this.socket.sendFrame.bind(this.socket);
+  socketServerOffers = this.socket.serverOffers.bind(this.socket);
   listCloudNotes = this.notes.listNotes.bind(this.notes);
   getCloudNote = this.notes.getNote.bind(this.notes);
   putCloudNote = this.notes.putNote.bind(this.notes);
@@ -731,10 +741,12 @@ class GloomApiClient {
   getCloudHistory = this.data.getCloudHistory.bind(this.data);
   getCloudExchangeRate = this.data.getCloudExchangeRate.bind(this.data);
   getCloudEconomicCalendar = this.data.getCloudEconomicCalendar.bind(this.data);
+  getCloudMacroReleaseDays = this.data.getCloudMacroReleaseDays.bind(this.data);
   getCloudEquityDiagnostic = this.data.getCloudEquityDiagnostic.bind(this.data);
   getCloudEarningsCalendar = this.data.getCloudEarningsCalendar.bind(this.data);
   getCloudEarningsHistory = this.data.getCloudEarningsHistory.bind(this.data);
   getCloudFredSeries = this.data.getCloudFredSeries.bind(this.data);
+  getCloudFredSeriesCatalog = this.data.getCloudFredSeriesCatalog.bind(this.data);
   getCloudCryptoMarkets = this.data.getCloudCryptoMarkets.bind(this.data);
   getCloudCentralBankRates = this.data.getCloudCentralBankRates.bind(this.data);
   getMobileAlertHistory = this.data.getMobileAlertHistory.bind(this.data);
@@ -763,6 +775,7 @@ class GloomApiClient {
   getCloudSocialMentionPosts = this.data.getCloudSocialMentionPosts.bind(this.data);
   getCloudFuturesCurve = this.data.getCloudFuturesCurve.bind(this.data);
   getCloudFuturesCurveAsOf = this.data.getCloudFuturesCurveAsOf.bind(this.data);
+  getCloudFuturesContract = this.data.getCloudFuturesContract.bind(this.data);
   getCloudRatePath = this.data.getCloudRatePath.bind(this.data);
   getCloudShiller = this.data.getCloudShiller.bind(this.data);
   getCloudCotBoard = this.data.getCloudCotBoard.bind(this.data);
@@ -803,6 +816,7 @@ class GloomApiClient {
   getCloudTape = this.data.getCloudTape.bind(this.data);
   getCloudYieldCurve = this.data.getCloudYieldCurve.bind(this.data);
   getCloudCurve = this.data.getCloudCurve.bind(this.data);
+  getCloudCurveHistory = this.data.getCloudCurveHistory.bind(this.data);
   getCloudWorldCurves = this.data.getCloudWorldCurves.bind(this.data);
   getCloudCds = this.data.getCloudCds.bind(this.data);
   getCloudCdsHistory = this.data.getCloudCdsHistory.bind(this.data);
@@ -831,6 +845,7 @@ class GloomApiClient {
   updateCloudSavedSearch = this.data.updateCloudSavedSearch.bind(this.data);
   deleteCloudSavedSearch = this.data.deleteCloudSavedSearch.bind(this.data);
   getCloudNews = this.data.getCloudNews.bind(this.data);
+  searchCloudNews = this.data.searchCloudNews.bind(this.data);
   getCloudNewsStory = this.data.getCloudNewsStory.bind(this.data);
   getCloudTickerTweets = this.data.getCloudTickerTweets.bind(this.data);
   searchCloudTweets = this.data.searchCloudTweets.bind(this.data);

package/src/api-client/market-discovery.ts

@@ -1,4 +1,4 @@
-import type { CloudCorporateActionsPayload, CloudQuotePayload } from "./types";
+import type { CloudCorporateActionsPayload, CloudMoverSessionFields, CloudQuotePayload } from "./types";
 
 export interface ScreenerQuote {
   symbol: string;
@@ -19,6 +19,8 @@ export interface ScreenerQuote {
   lastUpdated?: number;
   /** Session-fixed, so the price column reads its decimals from it rather than from each tick. */
   previousClose?: number;
+  /** The quote's sessions beside the live print the list ranks by, when the server sends them. */
+  sessions?: CloudMoverSessionFields;
 }
 
 
@@ -63,6 +65,13 @@ export interface MarketHeatmapResult {
   session?: "REGULAR" | "PRE" | "POST" | "CLOSED" | null;
   /** The completed regular session every stored tile describes outside the regular session, as a New York date; null while it trades. */
   regularSessionDate?: string | null;
+  /**
+   * When that session closed, in epoch milliseconds: its real close from the
+   * exchange calendar, so an early close reads 13:00 New York. Null while a
+   * session trades and when the snapshot names no session; an older server
+   * leaves it out.
+   */
+  regularSessionClosedAt?: number | null;
   assets: MarketHeatmapAsset[];
 }
 

package/src/api-client/normalizers.ts

@@ -1,7 +1,10 @@
 import type {
+  ChatAccountType,
   ChatAttachment,
   ChatChannel,
+  ChatDiscordLink,
   ChatMessage,
+  ChatMessageOrigin,
   ChatNotification,
   ChatStateResponse,
   CloudSavedSearch,
@@ -74,9 +77,20 @@ export function normalizeChatAttachments(value: unknown): ChatAttachment[] {
   });
 }
 
+const CHAT_ACCOUNT_TYPES: readonly string[] = ["human", "managed_llm", "discord"] satisfies ChatAccountType[];
+const CHAT_MESSAGE_ORIGINS: readonly string[] = ["app", "discord"] satisfies ChatMessageOrigin[];
+
+/** A value a newer server adds that this client does not know reads as absent: a human, a message from the app. */
+function chatUserWithKnownAccountType(user: ChatMessage["user"]): ChatMessage["user"] {
+  if (!user || user.accountType === undefined || CHAT_ACCOUNT_TYPES.includes(user.accountType)) return user;
+  const { accountType: _unknown, ...known } = user;
+  return known;
+}
+
 export function normalizeChatMessage(message: ChatMessage): ChatMessage {
   const normalized: ChatMessage = {
     ...message,
+    user: chatUserWithKnownAccountType(message.user),
     content: typeof message.content === "string" ? message.content : "",
     createdAt: normalizeTimestamp(message.createdAt),
     ...(message.editedAt
@@ -84,12 +98,25 @@ export function normalizeChatMessage(message: ChatMessage): ChatMessage {
       : {}),
   };
   if ("attachments" in message) normalized.attachments = normalizeChatAttachments(message.attachments);
+  if (message.origin !== undefined && !CHAT_MESSAGE_ORIGINS.includes(message.origin)) delete normalized.origin;
   if (message.attachmentReview !== "pending" && message.attachmentReview !== "failed") {
     delete normalized.attachmentReview;
   }
   return normalized;
 }
 
+/** The link answer of a server that knows Discord: mirroring is on and linking available unless it says otherwise. */
+export function normalizeChatDiscordLink(value: unknown): ChatDiscordLink {
+  const raw = value && typeof value === "object" ? value as Record<string, unknown> : {};
+  const username = typeof raw.discordUsername === "string" ? raw.discordUsername.trim() : "";
+  return {
+    linked: raw.linked === true,
+    ...(username ? { discordUsername: username } : {}),
+    mirror: raw.mirror !== false,
+    available: raw.available !== false,
+  };
+}
+
 export function normalizeChatMessages(messages: ChatMessage[]): ChatMessage[] {
   return messages.map((message) => normalizeChatMessage(message));
 }

package/src/api-client/paths.ts

@@ -7,6 +7,7 @@ import { isUsListingExchange, normalizeSymbol, parsePublicTickerKey, publicTicke
 import { nonUsSecListingVenue } from "../utils/sec";
 import type { HistoryRetention } from "../sources/history-retention";
 import type { CloudBeneficialOwnersParams } from "./beneficial-owners";
+import type { RevenueBreakdownView } from "./revenue-breakdown";
 
 export type CloudHistoryParams = {
   interval?: string;
@@ -58,7 +59,15 @@ export type CloudCongressHouseParams = {
   minAmount?: number;
 };
 
-export type CloudEarningsCallsParams = {
+/** The listing an issuer lookup is for, so a listing abroad never reads a US namesake. */
+export type IssuerListingParams = {
+  /** The listing's venue. Sent only for a venue outside the US, with `name`. */
+  exchange?: string;
+  /** The listing's company name, from its ticker or its own quote. */
+  name?: string;
+};
+
+export type CloudEarningsCallsParams = IssuerListingParams & {
   ticker?: string;
   limit?: number;
   offset?: number;
@@ -305,11 +314,42 @@ export function cloudJobsMoversPath(limit?: number, offset?: number): string {
   return appendQuery("/cloud/jobs", search);
 }
 
+/** A listing outside the US, as an issuer lookup names it: its bare symbol, venue and company. */
+export interface ListingAbroad {
+  symbol: string;
+  exchange: string;
+  name?: string;
+}
+
+/**
+ * The listing abroad a ticker names, from its key or the given venue: AI in
+ * Paris is Air Liquide, AI in New York is C3.ai. Null for a US listing, a
+ * routing destination or a symbol with no venue, which keep their US lookup.
+ */
+export function listingAbroad(ticker: string, exchange?: string, name?: string | null): ListingAbroad | null {
+  const venue = nonUsSecListingVenue(ticker, exchange);
+  if (!venue) return null;
+  const company = name?.trim();
+  return { symbol: parsePublicTickerKey(ticker).symbol, exchange: venue, ...(company ? { name: company } : {}) };
+}
+
+/** Sets a listing abroad's venue and company on an issuer lookup. */
+function setListingAbroad(search: URLSearchParams, listing: ListingAbroad | null): void {
+  if (!listing) return;
+  search.set("exchange", listing.exchange);
+  if (listing.name) search.set("name", listing.name);
+}
+
+/** A US listing or a bare symbol looks up its US ticker as before; a listing abroad names its venue and company. */
 export function cloudEarningsCallsPath(
   params: CloudEarningsCallsParams = {},
 ): string {
   const search = new URLSearchParams();
-  if (params.ticker) search.set("ticker", normalizeIssuerResearchTicker(params.ticker));
+  if (params.ticker) {
+    const abroad = listingAbroad(params.ticker, params.exchange, params.name);
+    search.set("ticker", abroad?.symbol ?? normalizeIssuerResearchTicker(params.ticker));
+    setListingAbroad(search, abroad);
+  }
   if (params.limit != null) search.set("limit", String(params.limit));
   if (params.offset != null) search.set("offset", String(params.offset));
   if (params.includePending) search.set("includePending", "true");
@@ -320,33 +360,60 @@ export function cloudEarningsTranscriptPath(id: string): string {
   return `/cloud/transcripts/${encodeURIComponent(id)}`;
 }
 
+/**
+ * An issuer read's path: a US listing or a bare symbol keeps its US ticker
+ * and sends nothing else; a listing abroad sends its bare symbol with its
+ * venue and company (listingAbroad).
+ */
+function issuerPath(base: string, ticker: string, listing: IssuerListingParams = {}, suffix = ""): string {
+  const abroad = listingAbroad(ticker, listing.exchange, listing.name);
+  const search = new URLSearchParams();
+  setListingAbroad(search, abroad);
+  return appendQuery(`${base}/${encodeURIComponent(abroad?.symbol ?? normalizeIssuerResearchTicker(ticker))}${suffix}`, search);
+}
+
 /**
  * RISK, EXEC and EK are Pro: these reads need a verified Pro account. The same
  * risk factors and pay are open under /public for the gloom.sh pages.
  */
-export function cloudProxyStatementsPath(ticker: string): string {
-  return `/cloud/proxies/${encodeURIComponent(normalizeIssuerResearchTicker(ticker))}`;
+export function cloudProxyStatementsPath(ticker: string, listing?: IssuerListingParams): string {
+  return issuerPath("/cloud/proxies", ticker, listing);
 }
 
-export function cloudFilingEventsPath(ticker: string, limit?: number): string {
+export function cloudFilingEventsPath(ticker: string, limit?: number, listing: IssuerListingParams = {}): string {
+  const abroad = listingAbroad(ticker, listing.exchange, listing.name);
   const search = new URLSearchParams();
+  setListingAbroad(search, abroad);
   if (limit != null) search.set("limit", String(limit));
-  return appendQuery(
-    `/cloud/events/${encodeURIComponent(normalizeIssuerResearchTicker(ticker))}`,
-    search,
-  );
+  return appendQuery(`/cloud/events/${encodeURIComponent(abroad?.symbol ?? normalizeIssuerResearchTicker(ticker))}`, search);
 }
 
-export function cloudRiskReportsPath(ticker: string): string {
-  return `/cloud/risks/${encodeURIComponent(normalizeIssuerResearchTicker(ticker))}`;
+export function cloudRiskReportsPath(ticker: string, listing?: IssuerListingParams): string {
+  return issuerPath("/cloud/risks", ticker, listing);
 }
 
-export function cloudRiskReportPath(ticker: string, year: number): string {
-  return `/cloud/risks/${encodeURIComponent(normalizeIssuerResearchTicker(ticker))}/${year}`;
+export function cloudRiskReportPath(ticker: string, year: number, listing?: IssuerListingParams): string {
+  return issuerPath("/cloud/risks", ticker, listing, `/${year}`);
 }
 
-export function cloudProxyStatementPath(ticker: string, year: number): string {
-  return `/cloud/proxies/${encodeURIComponent(normalizeIssuerResearchTicker(ticker))}/${year}`;
+export function cloudProxyStatementPath(ticker: string, year: number, listing?: IssuerListingParams): string {
+  return issuerPath("/cloud/proxies", ticker, listing, `/${year}`);
+}
+
+/** The principal maturity schedule; a US symbol goes as given, as it always has. */
+export function cloudDebtMaturitiesPath(symbol: string, listing: IssuerListingParams = {}): string {
+  const abroad = listingAbroad(symbol, listing.exchange, listing.name);
+  const search = new URLSearchParams({ symbol: abroad?.symbol ?? symbol });
+  setListingAbroad(search, abroad);
+  return appendQuery("/cloud/debt-maturities", search);
+}
+
+export function cloudRevenueBreakdownPath(symbol: string, view?: RevenueBreakdownView, listing: IssuerListingParams = {}): string {
+  const abroad = listingAbroad(symbol, listing.exchange, listing.name);
+  const search = new URLSearchParams({ symbol: abroad?.symbol ?? symbol });
+  setListingAbroad(search, abroad);
+  if (view) search.set("view", view);
+  return appendQuery("/cloud/revenue-breakdown", search);
 }
 
 /**
@@ -355,23 +422,21 @@ export function cloudProxyStatementPath(ticker: string, year: number): string {
  * its symbol can be another company's US ticker.
  */
 export function cloudSecFilingsPath(params: CloudSecFilingsParams): string {
-  const venue = nonUsSecListingVenue(params.ticker, params.exchange);
+  const abroad = listingAbroad(params.ticker, params.exchange, params.name);
   const search = new URLSearchParams({
-    ticker: venue ? parsePublicTickerKey(params.ticker).symbol : normalizeIssuerResearchTicker(params.ticker),
+    ticker: abroad?.symbol ?? normalizeIssuerResearchTicker(params.ticker),
   });
   if (params.limit != null) search.set("limit", String(params.limit));
   if (params.offset != null) search.set("offset", String(params.offset));
-  if (venue) {
-    search.set("exchange", venue);
-    const name = params.name?.trim();
-    if (name) search.set("name", name);
-  }
+  setListingAbroad(search, abroad);
   return appendQuery("/cloud/sec/filings", search);
 }
 
 /** Schedule 13D and 13G reports about the issuer behind `ticker`. */
 export function cloudSecBeneficialOwnersPath(params: CloudBeneficialOwnersParams): string {
-  const search = new URLSearchParams({ ticker: normalizeIssuerResearchTicker(params.ticker) });
+  const abroad = listingAbroad(params.ticker, params.exchange, params.name);
+  const search = new URLSearchParams({ ticker: abroad?.symbol ?? normalizeIssuerResearchTicker(params.ticker) });
+  setListingAbroad(search, abroad);
   if (params.form) search.set("form", params.form);
   if (params.history) search.set("history", "1");
   if (params.limit != null) search.set("limit", String(params.limit));
@@ -511,6 +576,13 @@ export function cloudNewsPath(params: CloudNewsParams = {}): string {
   return appendQuery("/news", search);
 }
 
+/** Stories whose headline, summary or publisher matches the text, best match first; the service takes at most 100. */
+export function cloudNewsSearchPath(query: string, limit?: number): string {
+  const search = new URLSearchParams({ query });
+  if (limit != null) search.set("limit", String(limit));
+  return appendQuery("/news/search", search);
+}
+
 export function cloudTickerTweetsPath(params: CloudTickerTweetsParams): string {
   const search = new URLSearchParams({ ticker: params.ticker });
   if (params.limit != null) search.set("limit", String(params.limit));

package/src/api-client/request.ts

@@ -16,7 +16,8 @@ import {
 } from "../core/connection-health";
 import { SESSION_COOKIE_NAMES } from "./session-cookie";
 
-const DEFAULT_API_URL = "https://api.gloom.sh";
+/** The public Gloom Cloud API, which the web app's same-origin `/api` path forwards to. */
+export const DEFAULT_API_URL = "https://api.gloom.sh";
 const DEFAULT_MARKET_REQUEST_TIMEOUT_MS = 10_000;
 const DEFAULT_RESEARCH_REQUEST_TIMEOUT_MS = 45_000;
 // Research may fill missing sections after a primary read; quote/history reads remain latency bounded.

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

@@ -3,8 +3,12 @@ import { getCurrentPluginTarget } from "../plugins/current-target";
 import type { DesktopDeepLinkBridge } from "../types/desktop-deeplink";
 import { exposeExperiment, storedExperimentAssignments } from "./web-experiments";
 import { createWallExperimentSession, type WallExperiment, type WallExperimentContext, type WallTeaserVariant } from "./wall-experiments";
+import { createUpgradeExperimentSession, UPGRADE_PERSONALIZED, type UpgradeExperimentContext, type UpgradePersonalizedVariant } from "./upgrade-experiment";
 import { hasProAccess } from "./plan-rules";
 import { withDeadline } from "../utils/async-deadline";
+import { browserDoNotTrack } from "../telemetry/crash-reports-dom";
+import { currentTelemetryConfig } from "../telemetry/live-config";
+import { usageTelemetryAllowed } from "../telemetry/usage-counts";
 
 export type ResearchActivity =
   | "workspace_opened"
@@ -38,6 +42,7 @@ let anonymousId: string | undefined;
 let attribution: Record<string, string> = {};
 const wallExperiment = createWallExperimentSession();
 const signinWallExperiment = createWallExperimentSession("wall_teaser_signin");
+const upgradeExperiment = createUpgradeExperimentSession();
 const WALL_VIEWS_SESSION_KEY = "gloomberb.wall-teaser.views";
 
 const ATTRIBUTION_STORAGE_KEY = "gloomberb.web.attribution";
@@ -232,12 +237,7 @@ function stripHandoffParams(url: URL): void {
 /** 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;
+    if (!researchTelemetryAllowed()) return;
     const url = new URL(location.href);
     const incoming = readHandoffId(url);
     const stored = localStorage.getItem(ANONYMOUS_ID_STORAGE_KEY);
@@ -267,6 +267,7 @@ export function initializeBrowserResearchActivity(): void {
  */
 export function initializeDesktopResearchActivity(storage: StorageLike = localStorage): void {
   try {
+    if (!researchTelemetryAllowed()) return;
     const stored = storage.getItem(ANONYMOUS_ID_STORAGE_KEY);
     anonymousId = stored && ANONYMOUS_ID.test(stored) ? stored : undefined;
     attribution = readStoredAttribution(storage.getItem(ATTRIBUTION_STORAGE_KEY));
@@ -276,6 +277,7 @@ export function initializeDesktopResearchActivity(storage: StorageLike = localSt
 }
 
 export function adoptDesktopHandoff(href: string, storage: StorageLike = localStorage, now = Date.now()): boolean {
+  if (!researchTelemetryAllowed()) return false;
   if (!carriesHandoff(href)) return false;
   try {
     const url = new URL(href);
@@ -367,6 +369,7 @@ export function recordResearchActivity(
   tab?: string,
   { desks, placement: rawPlacement, teaser_kind, cta }: ResearchActivityDetails = {},
 ): void {
+  if (!researchTelemetryAllowed()) return;
   const target = getCurrentPluginTarget();
   const user = apiClient.getCurrentUser();
   const wallEvent = event === "wall_viewed" || event === "wall_cta_clicked";
@@ -449,6 +452,7 @@ function webExperimentAttribution(): { experiments?: string } {
  * Privacy Control) and not driven by automation are asked. See web-experiments.ts.
  */
 export function exposeWebExperiment(experiment: string): Promise<string | null> {
+  if (!researchTelemetryAllowed()) return Promise.resolve(null);
   if (getCurrentPluginTarget() !== "web") return Promise.resolve(null);
   try {
     return exposeExperiment(experiment, {
@@ -471,11 +475,13 @@ export function exposeWebExperiment(experiment: string): Promise<string | null>
   }
 }
 
+/** Research milestones, attribution and exposures share the Usage off switch. */
+function researchTelemetryAllowed(): boolean {
+  return usageTelemetryAllowed(currentTelemetryConfig(undefined)) && !browserDoNotTrack();
+}
+
 function wallPrivacyBlocked(): boolean {
-  if (typeof navigator === "undefined") return false;
-  return navigator.doNotTrack === "1"
-    || (navigator as Navigator & { globalPrivacyControl?: boolean }).globalPrivacyControl === true
-    || navigator.webdriver === true;
+  return !researchTelemetryAllowed() || (typeof navigator !== "undefined" && navigator.webdriver === true);
 }
 
 function wallExperimentContext(): WallExperimentContext {
@@ -524,6 +530,35 @@ export function exposeWallTeaser(experiment: WallExperiment = "wall_teaser"): Pr
   });
 }
 
+function upgradeExperimentContext(): UpgradeExperimentContext {
+  const { accountId, pro, optedOut, automated, session } = wallExperimentContext();
+  return { accountId, pro, optedOut, automated, session };
+}
+
+/** The `upgrade_personalized` arm this session already has, without asking; see upgrade-experiment.ts. */
+export function knownUpgradePersonalized(): UpgradePersonalizedVariant | null | undefined {
+  return upgradeExperiment.known(upgradeExperimentContext());
+}
+
+/**
+ * Asks for the `upgrade_personalized` arm when an upgrade surface is shown to
+ * a free account that has tickers to name, once per account and session. The
+ * request says where it showed and nothing about the holdings.
+ */
+export function exposeUpgradePersonalized(placement: string): Promise<UpgradePersonalizedVariant | null> {
+  const context = upgradeExperimentContext();
+  const surface = getCurrentPluginTarget();
+  return upgradeExperiment.expose(context, () => {
+    const controller = new AbortController();
+    return withDeadline(apiClient.recordExperimentExposure({
+      eventId: crypto.randomUUID(),
+      surface,
+      experiment: UPGRADE_PERSONALIZED,
+      ...(ACTIVITY_ID.test(placement) ? { placement } : {}),
+    }, controller.signal), 3_000, "Upgrade experiment request timed out", (error) => controller.abort(error));
+  });
+}
+
 /** Records the visible wall once per placement, including visitors outside the experiment. */
 export function recordWallViewed(placement: string, teaserKind?: "summary" | "sample" | "none"): void {
   recordResearchActivity("wall_viewed", undefined, undefined, { placement, teaser_kind: teaserKind });
@@ -537,6 +572,7 @@ export function recordWallCtaClicked(placement: string, cta: "login" | "signup")
 export function researchUpgradeUrl(returnTo?: string): string {
   const url = new URL("https://gloom.sh/cloud?upgrade=pro");
   if (returnTo) url.searchParams.set("returnTo", returnTo);
+  if (!researchTelemetryAllowed()) return url.href;
   if (anonymousId) url.searchParams.set(HANDOFF_ID_KEY, anonymousId);
   for (const [key, value] of Object.entries(attribution)) {
     if (/^(utm_(source|medium|campaign|content|term)|twclid)$/.test(key))

package/src/api-client/socket.ts

@@ -33,7 +33,9 @@ const QUOTE_SUBSCRIPTION_FLUSH_MS = 25;
 const MARKET_BATCH_FEATURE = "market.batch";
 /** Chat frames carry `attachments`; without it the server writes images into the text. */
 export const CHAT_ATTACHMENTS_FEATURE = "chat.attachments";
-const CLIENT_SOCKET_FEATURES = [MARKET_BATCH_FEATURE, CHAT_ATTACHMENTS_FEATURE] as const;
+/** The app can run terminal tools relayed from a remote assistant; it still announces itself first. */
+export const TERMINAL_RELAY_FEATURE = "terminal.relay";
+const CLIENT_SOCKET_FEATURES = [MARKET_BATCH_FEATURE, CHAT_ATTACHMENTS_FEATURE, TERMINAL_RELAY_FEATURE] as const;
 const cloudApiLog = debugLog.createLogger("cloud-api");
 
 type ChannelListener = (message: ChatMessage) => void;
@@ -131,6 +133,7 @@ export class CloudApiSocket {
   /** What the last "ready" frame offered; kept across reconnects so a blip does not hide features. */
   private offeredFeatures: ReadonlySet<string> = new Set();
   private readonly offeredFeatureListeners = new Set<() => void>();
+  private readonly connectionListeners = new Set<(event: "ready" | "closed") => void>();
   private readonly tapeListeners = new Map<string, { symbol: string; exchange: string; listeners: Set<(event: TapeFeedEvent) => void> }>();
   private readonly scannerListeners = new Map<
     ScannerKind,
@@ -164,6 +167,7 @@ export class CloudApiSocket {
     const ws = this.ws;
     this.ws = null;
     if (ws) {
+      this.emitConnection("closed");
       cloudApiLog.info("teardown websocket");
       this.health.reportSocketState(
         GLOOM_CLOUD_SOCKET_CONNECTION_ID,
@@ -260,6 +264,29 @@ export class CloudApiSocket {
     };
   }
 
+  /** "ready" after each server hello (features negotiated), "closed" when that connection ends. */
+  subscribeConnection(listener: (event: "ready" | "closed") => void): () => void {
+    this.connectionListeners.add(listener);
+    return () => {
+      this.connectionListeners.delete(listener);
+    };
+  }
+
+  /** Sends one frame on the open connection; false when there is none. */
+  sendFrame(payload: Record<string, unknown>): boolean {
+    if (this.ws?.readyState !== WebSocket.OPEN) return false;
+    try {
+      this.ws.send(JSON.stringify(payload));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  private emitConnection(event: "ready" | "closed"): void {
+    for (const listener of this.connectionListeners) listener(event);
+  }
+
   subscribeTeamNotifications(listener: TeamNotificationListener): () => void {
     this.teamNotificationListeners.add(listener);
     this.syncAuthState();
@@ -470,6 +497,7 @@ export class CloudApiSocket {
     });
     this.channelListeners.clear();
     this.offeredFeatureListeners.clear();
+    this.connectionListeners.clear();
     this.chatNotificationListeners.clear();
     this.chatPresenceListeners.clear();
     this.teamNotificationListeners.clear();
@@ -500,13 +528,15 @@ export class CloudApiSocket {
     if (parsed?.type === "ready") {
       recordServerClockSample(parsed.serverTime);
       this.negotiateSocketFeatures(parsed.features);
-      if (!parsed.user) return;
-      cloudApiLog.info("websocket ready", {
-        emailVerified: parsed.user.emailVerified === true,
-      });
-      this.delegate.updateCurrentUserFromSocket(
-        parsed.user as Partial<AuthUser>,
-      );
+      if (parsed.user) {
+        cloudApiLog.info("websocket ready", {
+          emailVerified: parsed.user.emailVerified === true,
+        });
+        this.delegate.updateCurrentUserFromSocket(
+          parsed.user as Partial<AuthUser>,
+        );
+      }
+      this.emitConnection("ready");
       return;
     }
 
@@ -769,6 +799,7 @@ export class CloudApiSocket {
         tokenSource: usingWebSocketToken ? "websocket" : "session",
       });
       if (!activeSocket) return;
+      this.emitConnection("closed");
       this.health.reportSocketState(
         GLOOM_CLOUD_SOCKET_CONNECTION_ID,
         "closed",