gloomberb 0.15.2 → 0.15.4

package/src/market-data/realized-volatility.ts

@@ -0,0 +1,292 @@
+import type { PricePoint } from "../types/financials";
+import {
+  mergePriceHistoryIntegrity,
+  pricePointIntegrity,
+  type PriceHistoryIntegrity,
+} from "../utils/price-history-integrity";
+
+export const VOLATILITY_TRADING_DAYS = 252;
+export const REALIZED_VOLATILITY_WINDOWS = [10, 20, 30, 60, 90, 180, 260] as const;
+
+export const REALIZED_VOLATILITY_ESTIMATORS = [
+  "close-to-close", "parkinson", "garman-klass", "rogers-satchell", "yang-zhang",
+] as const;
+export type RealizedVolatilityEstimator = typeof REALIZED_VOLATILITY_ESTIMATORS[number];
+
+export function isRealizedVolatilityEstimator(value: unknown): value is RealizedVolatilityEstimator {
+  return REALIZED_VOLATILITY_ESTIMATORS.some((estimator) => estimator === value);
+}
+
+export type RealizedVolatilityUnavailableReason =
+  | "invalid-window"
+  | "invalid-date"
+  | "insufficient-history"
+  | "inconsistent-ohlc"
+  | "missing-close"
+  | "missing-ohlc"
+  | "invalid-variance";
+
+export interface RealizedVolatilityResult {
+  /** Annualized decimal volatility, so 0.2 means 20%. */
+  value: number | null;
+  reason?: RealizedVolatilityUnavailableReason;
+  integrity?: PriceHistoryIntegrity;
+}
+
+export interface RollingRealizedVolatilityOptions {
+  windows?: readonly number[];
+  estimator?: RealizedVolatilityEstimator;
+}
+
+export interface RollingRealizedVolatilityPoint {
+  date: Date;
+  /** Values stay null across incomplete or rejected windows. */
+  values: Readonly<Record<number, number | null>>;
+}
+
+export interface VolatilityConeOptions extends RollingRealizedVolatilityOptions {
+  /** Calendar years ending on the last supplied observation, not on today's date. */
+  lookbackYears?: 1 | 2;
+}
+
+export interface VolatilityConeStatistics {
+  window: number;
+  current: number | null;
+  min: number | null;
+  max: number | null;
+  mean: number | null;
+  median: number | null;
+  /** Midrank percentile on a 0 to 100 scale; a constant history has rank 50. */
+  percentile: number | null;
+  sampleSize: number;
+}
+
+/**
+ * Consumer guard for daily-data requests whose provider may have fallen back to
+ * intraday or weekly bars. The estimators themselves remain general n-session
+ * calculations. This detects cadence contradictions, not missing market sessions.
+ */
+export function realizedVolatilityCadenceIssue(points: readonly Pick<PricePoint, "date">[]): string | null {
+  const timestamps = new Set<number>();
+  for (const point of points) {
+    const time = new Date(point.date).getTime();
+    if (!Number.isFinite(time)) return "Realized volatility unavailable: invalid history date";
+    timestamps.add(time);
+  }
+  const history = [...timestamps].sort((a, b) => a - b);
+  const days = new Set<number>();
+  const gaps: number[] = [];
+  for (let index = 0; index < history.length; index += 1) {
+    const time = history[index]!;
+    const day = Math.floor(time / 86_400_000);
+    if (days.has(day)) return "Daily history unavailable: intraday observations returned";
+    days.add(day);
+    if (index > 0) gaps.push(time - history[index - 1]!);
+  }
+  if (gaps.length === 0) return null;
+  gaps.sort((a, b) => a - b);
+  const middle = Math.floor(gaps.length / 2);
+  const median = gaps.length % 2 ? gaps[middle]! : (gaps[middle - 1]! + gaps[middle]!) / 2;
+  return median >= 5 * 86_400_000 ? "Daily history unavailable: observed cadence is weekly or slower" : null;
+}
+
+interface Observation {
+  time: number;
+  close: number | null;
+  open: number | null;
+  high: number | null;
+  low: number | null;
+  integrity?: PriceHistoryIntegrity;
+}
+
+function positiveLog(value: number | undefined): number | null {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.log(value) : null;
+}
+
+/** Corrections replace the same date before selection, matching the options monitor. */
+function observations(points: readonly PricePoint[]): Observation[] | null {
+  const dates = new Map<number, PricePoint>();
+  for (const point of points) {
+    const time = new Date(point.date).getTime();
+    if (!Number.isFinite(time)) return null;
+    dates.set(time, point);
+  }
+  return [...dates.entries()].sort(([a], [b]) => a - b).map(([time, point]) => ({
+    time,
+    close: positiveLog(point.close),
+    open: positiveLog(point.open),
+    high: positiveLog(point.high),
+    low: positiveLog(point.low),
+    integrity: pricePointIntegrity(point),
+  }));
+}
+
+function validWindow(window: number): boolean {
+  return Number.isInteger(window) && window >= 2;
+}
+
+/** Welford's centered variance avoids cancellation when the return drift is large. */
+function sampleVariance(values: readonly number[]): number {
+  let mean = 0;
+  let squaredDeviations = 0;
+  for (let index = 0; index < values.length; index += 1) {
+    const value = values[index]!;
+    const delta = value - mean;
+    mean += delta / (index + 1);
+    squaredDeviations += delta * (value - mean);
+  }
+  return squaredDeviations / (values.length - 1);
+}
+
+function unavailable(reason: RealizedVolatilityUnavailableReason): RealizedVolatilityResult {
+  return { value: null, reason };
+}
+
+function estimateWindow(
+  history: readonly Observation[],
+  end: number,
+  window: number,
+  estimator: RealizedVolatilityEstimator,
+): RealizedVolatilityResult {
+  if (!validWindow(window)) return unavailable("invalid-window");
+  const previousCloseRequired = estimator === "close-to-close" || estimator === "yang-zhang";
+  const start = end - window + 1;
+  const first = start - (previousCloseRequired ? 1 : 0);
+  // Validate selected observations before calculating. Removing one would bridge a gap.
+  // Even an incomplete window retains diagnostics for its rejected source rows.
+  const rejected: PriceHistoryIntegrity[] = [];
+  for (let index = Math.max(0, first); index <= end; index += 1) {
+    const integrity = history[index]!.integrity;
+    if (integrity) rejected.push(integrity);
+  }
+  if (rejected.length > 0) {
+    return { value: null, reason: "inconsistent-ohlc", integrity: mergePriceHistoryIntegrity(...rejected) };
+  }
+  for (let index = Math.max(0, first); index <= end; index += 1) {
+    const point = history[index]!;
+    if (point.close === null) return unavailable("missing-close");
+    // The predecessor supplies only its close, including for Yang-Zhang.
+    if (estimator !== "close-to-close" && index >= start
+      && (point.high === null || point.low === null || (estimator !== "parkinson" && point.open === null))) {
+      return unavailable("missing-ohlc");
+    }
+  }
+  if (first < 0) return unavailable("insufficient-history");
+
+  const returns: number[] = [];
+  const overnightReturns: number[] = [];
+  let rangeSum = 0;
+  for (let index = start; index <= end; index += 1) {
+    const point = history[index]!;
+    const close = point.close!;
+    if (estimator === "close-to-close") {
+      // Subtract logs: even two finite prices can have an overflowing ratio.
+      returns.push(close - history[index - 1]!.close!);
+      continue;
+    }
+    const high = point.high!;
+    const low = point.low!;
+    const range = high - low;
+    if (estimator === "parkinson") {
+      rangeSum += range * range / (4 * Math.LN2);
+    } else if (estimator === "garman-klass") {
+      const intraday = close - point.open!;
+      rangeSum += 0.5 * range * range - (2 * Math.LN2 - 1) * intraday * intraday;
+    } else {
+      const open = point.open!;
+      rangeSum += (high - open) * (high - close) + (low - open) * (low - close);
+      if (estimator === "yang-zhang") {
+        returns.push(close - open);
+        overnightReturns.push(open - history[index - 1]!.close!);
+      }
+    }
+  }
+
+  let variance: number;
+  if (estimator === "close-to-close") {
+    variance = sampleVariance(returns);
+  } else if (estimator === "yang-zhang") {
+    const weight = 0.34 / (1.34 + (window + 1) / (window - 1));
+    variance = sampleVariance(overnightReturns) + weight * sampleVariance(returns) + (1 - weight) * rangeSum / window;
+  } else {
+    variance = rangeSum / window;
+  }
+  if (!Number.isFinite(variance) || variance < -64 * Number.EPSILON) return unavailable("invalid-variance");
+  // Integrity checks permit machine precision noise at an OHLC boundary.
+  return { value: Math.sqrt(Math.max(0, variance) * VOLATILITY_TRADING_DAYS) };
+}
+
+/**
+ * Latest n-session estimate. Close-to-close and Yang-Zhang need n+1 observations;
+ * range estimators need n. Holidays and missing sessions cannot be inferred without
+ * an exchange calendar. Supplied invalid observations remain gaps, never bridges.
+ */
+export function realizedVolatilityResult(
+  points: readonly PricePoint[],
+  window = 30,
+  estimator: RealizedVolatilityEstimator = "close-to-close",
+): RealizedVolatilityResult {
+  if (!validWindow(window)) return unavailable("invalid-window");
+  const history = observations(points);
+  return history === null ? unavailable("invalid-date") : estimateWindow(history, history.length - 1, window, estimator);
+}
+
+export function realizedVolatility(
+  points: readonly PricePoint[],
+  window = 30,
+  estimator: RealizedVolatilityEstimator = "close-to-close",
+): number | null {
+  return realizedVolatilityResult(points, window, estimator).value;
+}
+
+/** Invalid dates make chronology unknowable and return no series. */
+export function rollingRealizedVolatility(
+  points: readonly PricePoint[],
+  options: RollingRealizedVolatilityOptions = {},
+): RollingRealizedVolatilityPoint[] {
+  const history = observations(points);
+  if (history === null) return [];
+  const windows = [...new Set(options.windows ?? REALIZED_VOLATILITY_WINDOWS)];
+  const estimator = options.estimator ?? "close-to-close";
+  return history.map((point, index) => ({
+    date: new Date(point.time),
+    values: Object.fromEntries(windows.map((window) => [window, estimateWindow(history, index, window, estimator).value])),
+  }));
+}
+
+/** Rolling estimates end inside the calendar lookback; earlier bars supply warmup. */
+export function volatilityCone(
+  points: readonly PricePoint[],
+  options: VolatilityConeOptions = {},
+): VolatilityConeStatistics[] {
+  const windows = [...new Set(options.windows ?? REALIZED_VOLATILITY_WINDOWS)];
+  const series = rollingRealizedVolatility(points, { ...options, windows });
+  const latest = series.at(-1);
+  const cutoff = new Date(latest?.date ?? 0);
+  const month = cutoff.getUTCMonth();
+  cutoff.setUTCFullYear(cutoff.getUTCFullYear() - (options.lookbackYears ?? 1));
+  // February 29 maps to February 28 when the prior year is not a leap year.
+  if (cutoff.getUTCMonth() !== month) cutoff.setUTCDate(0);
+  const selected = series.filter((point) => point.date.getTime() > cutoff.getTime());
+  return windows.map((window) => {
+    const current = latest?.values[window] ?? null;
+    const values = selected.flatMap((point) => {
+      const value = point.values[window];
+      return value == null ? [] : [value];
+    }).sort((a, b) => a - b);
+    const sampleSize = values.length;
+    const midpoint = Math.floor(sampleSize / 2);
+    return {
+      window,
+      current,
+      min: values[0] ?? null,
+      max: values.at(-1) ?? null,
+      mean: sampleSize > 0 ? values.reduce((total, value) => total + value, 0) / sampleSize : null,
+      median: sampleSize > 0 ? (sampleSize % 2 ? values[midpoint]! : (values[midpoint - 1]! + values[midpoint]!) / 2) : null,
+      percentile: current !== null && sampleSize > 0
+        ? 100 * (values.filter((value) => value < current).length + 0.5 * values.filter((value) => value === current).length) / sampleSize
+        : null,
+      sampleSize,
+    };
+  });
+}

package/src/market-data/selectors.ts

@@ -1,4 +1,4 @@
-import type { MarketDataRequestContext } from "../types/data-provider";
+import type { MarketDataRequestContext, QuoteSubscriptionTarget } from "../types/data-provider";
 import type { Quote, TickerFinancials } from "../types/financials";
 import type { InstrumentRef, OptionsRequest, SecFilingsRequest, ChartRequest } from "./request-types";
 import type { QueryEntry } from "./result-types";
@@ -7,10 +7,6 @@ import { normalizePriceHistory } from "../utils/price-history";
 import { resolveTickerFinancialsQuoteState } from "./quotes/resolution";
 import { instrumentIdentityKey } from "../utils/instrument-identity";
 
-export function buildInstrumentKey(instrument: InstrumentRef): string {
-  return instrumentIdentityKey(instrument);
-}
-
 export function toMarketDataContext(instrument: InstrumentRef): MarketDataRequestContext {
   return {
     brokerId: instrument.brokerId,
@@ -19,18 +15,39 @@ export function toMarketDataContext(instrument: InstrumentRef): MarketDataReques
   };
 }
 
+/** The flat instrument a quote subscription target addresses. */
+export function instrumentFromQuoteTarget(target: QuoteSubscriptionTarget): InstrumentRef {
+  return {
+    symbol: target.symbol,
+    exchange: target.exchange,
+    brokerId: target.context?.brokerId,
+    brokerInstanceId: target.context?.brokerInstanceId,
+    instrument: target.context?.instrument ?? null,
+  };
+}
+
+/** One instrument per quote key, in the order the targets first name them. */
+export function uniqueQuoteInstruments(targets: readonly QuoteSubscriptionTarget[]): InstrumentRef[] {
+  const unique = new Map<string, InstrumentRef>();
+  for (const target of targets) {
+    const instrument = instrumentFromQuoteTarget(target);
+    unique.set(buildQuoteKey(instrument), instrument);
+  }
+  return [...unique.values()];
+}
+
 export function buildQuoteKey(instrument: InstrumentRef): string {
-  return `quote:${buildInstrumentKey(instrument)}`;
+  return `quote:${instrumentIdentityKey(instrument)}`;
 }
 
 export function buildSnapshotKey(instrument: InstrumentRef): string {
-  return `snapshot:${buildInstrumentKey(instrument)}`;
+  return `snapshot:${instrumentIdentityKey(instrument)}`;
 }
 
 export function buildChartKey(request: ChartRequest): string {
   return [
     "chart",
-    buildInstrumentKey(request.instrument),
+    instrumentIdentityKey(request.instrument),
     request.bufferRange,
     request.granularity ?? "range",
     request.resolution ?? "",
@@ -41,11 +58,11 @@ export function buildChartKey(request: ChartRequest): string {
 }
 
 export function buildOptionsKey(request: OptionsRequest): string {
-  return `options:${buildInstrumentKey(request.instrument)}:${request.expirationDate ?? "default"}`;
+  return `options:${instrumentIdentityKey(request.instrument)}:${request.expirationDate ?? "default"}`;
 }
 
 export function buildSecFilingsKey(request: SecFilingsRequest): string {
-  return `sec:${buildInstrumentKey(request.instrument)}:${request.count ?? 50}`;
+  return `sec:${instrumentIdentityKey(request.instrument)}:${request.count ?? 50}`;
 }
 
 export function buildSecContentKey(accessionNumber: string): string {

package/src/market-data/snapshot-provider.ts

@@ -2,7 +2,8 @@ import type { MarketDataRequestContext, DataProvider, CachedFinancialsTarget, Ti
 import type { OptionsChain, PricePoint, Quote, TickerFinancials } from "../types/financials";
 import { canonicalExchange, canonicalTickerKey, parsePublicTickerKey } from "../utils/exchanges";
 import { clipPriceHistoryToRange } from "../time-series/history-window";
-import { getPresetResolution, normalizeChartResolutionSupport, TIME_RANGE_ORDER, type ManualChartResolution } from "../time-series/resolution";
+import { getPresetResolution, normalizeChartResolutionSupport, type ManualChartResolution } from "../time-series/resolution";
+import { TIME_RANGES } from "../time-series/range";
 import type { InstrumentRef } from "./request-types";
 import { instrumentIdentityKey } from "../utils/instrument-identity";
 import { quoteMetadataFromQuote } from "./quotes/metadata";
@@ -54,7 +55,7 @@ export class SnapshotHistoryUnavailableError extends Error {
 }
 
 const SNAPSHOT_RESOLUTIONS = normalizeChartResolutionSupport(
-  TIME_RANGE_ORDER.map((maxRange) => ({ resolution: getPresetResolution(maxRange), maxRange })),
+  TIME_RANGES.map((maxRange) => ({ resolution: getPresetResolution(maxRange), maxRange })),
 );
 
 function lookup<T>(entries: ReadonlyArray<readonly [string, T]>) {

package/src/news/aggregator.ts

@@ -12,7 +12,6 @@ import {
   markDetailCapableArticle,
   mergeNewsArticle,
   newsArticleRevision,
-  normalizeNewsCategory,
   normalizeNewsFeed,
   normalizeNewsQuery,
 } from "./news-model";
@@ -573,38 +572,4 @@ export class NewsService {
     this.rebuildArticlePool();
     this.notify();
   }
-
-  getTopStories(count = 20): NewsArticle[] {
-    return [...this.articles]
-      .sort((a, b) => b.importance - a.importance)
-      .slice(0, count);
-  }
-
-  getFirehose(since?: Date, count = 100): NewsArticle[] {
-    let items = this.articles;
-    if (since) {
-      const sinceMs = since.getTime();
-      items = items.filter((item) => item.publishedAt.getTime() > sinceMs);
-    }
-    // articles is already sorted by publishedAt descending
-    return items.slice(0, count);
-  }
-
-  getBySector(sector: string, count = 50): NewsArticle[] {
-    const normalizedSector = normalizeNewsCategory(sector);
-    return this.articles
-      .filter((item) => [...item.sectors, ...item.categories].some((category) => normalizeNewsCategory(category) === normalizedSector))
-      .slice(0, count);
-  }
-
-  getBreaking(count = 20): NewsArticle[] {
-    const oneHourAgo = Date.now() - 60 * 60 * 1000;
-    return this.articles
-      .filter(
-        (item) =>
-          item.isBreaking ||
-          (item.publishedAt.getTime() >= oneHourAgo && item.importance >= 70),
-      )
-      .slice(0, count);
-  }
 }

package/src/news/source-label.ts

@@ -0,0 +1,22 @@
+/** Feed id words that name a section or a feed, never the publisher. */
+const SECTION_WORDS = new Set([
+  "all", "articles", "business", "companies", "current", "economy", "feed", "latest",
+  "markets", "news", "press", "public", "releases", "rss", "stories", "top", "topstories", "world",
+]);
+
+/**
+ * A publisher to show for a source id the service did not name (a service
+ * from before publishers): "acme-wire-news" reads "Acme Wire", "x-some_handle"
+ * reads "@some_handle", ids of three letters or fewer are acronyms (FT, SEC).
+ * A name that already reads as one is kept.
+ */
+export function readableNewsSource(value: string): string {
+  const trimmed = value.trim();
+  if (!trimmed || /\s|[A-Z]/.test(trimmed) || trimmed.includes(".")) return trimmed;
+  const words = trimmed.toLowerCase().split(/[-_]+/).filter(Boolean);
+  if (words[0] === "x" && words.length > 1) return `@${words.slice(1).join("_")}`;
+  const kept = words.filter((word) => !SECTION_WORDS.has(word));
+  return (kept.length > 0 ? kept : words)
+    .map((word) => (word.length <= 3 ? word.toUpperCase() : word.charAt(0).toUpperCase() + word.slice(1)))
+    .join(" ");
+}

package/src/news/types.ts

@@ -47,6 +47,7 @@ export interface NewsArticle {
 
 export interface NewsQuery {
   feed?: NewsFeed;
+  /** @deprecated Set `feed: "ticker"` instead. */
   scope?: NewsQueryScope;
   ticker?: string;
   exchange?: string;

package/src/pane-settings.ts

@@ -10,14 +10,6 @@ export function getPaneSettings(instance: PaneInstanceConfig | null | undefined)
   return clonePaneSettings(instance?.settings) ?? {};
 }
 
-export function getPaneSettingValue<T>(
-  instance: PaneInstanceConfig | null | undefined,
-  key: string,
-  fallback: T,
-): T {
-  return (instance?.settings?.[key] as T | undefined) ?? fallback;
-}
-
 export function updatePaneInstance(
   layout: LayoutConfig,
   paneId: string,

package/src/plugins/absorbed.ts

@@ -0,0 +1,33 @@
+import { pluginDirectoryNames } from "./plugin-names";
+
+/**
+ * Plugins that moved out into their own repositories and are built into
+ * Gloomberb again, under the same id.
+ *
+ * Anyone who used one while it was external still has its checkout in the
+ * plugins folder. Loading it beside the built-in fails on the duplicate id,
+ * so the loader, the installer and the updaters leave these checkouts alone.
+ * The folder itself stays: an older Gloomberb sharing the data directory may
+ * still load it.
+ */
+export const ABSORBED_PLUGINS = [
+  { id: "market-heatmap", name: "Market Heatmap", repo: "gloom-sh/gloom-market-heatmap", directory: "gloom-market-heatmap" },
+  { id: "market-halts", name: "Market Halts", repo: "gloom-sh/gloom-market-halts", directory: "gloom-market-halts" },
+  { id: "fear-greed", name: "Fear & Greed", repo: "gloom-sh/gloom-fear-greed", directory: "gloom-fear-greed" },
+  { id: "ipo-calendar", name: "IPO Calendar", repo: "gloom-sh/gloom-ipo-calendar", directory: "gloom-ipo-calendar" },
+] as const;
+
+export type AbsorbedPlugin = (typeof ABSORBED_PLUGINS)[number];
+
+/**
+ * The built-in a plugin folder or gloom.json id belongs to now, or null. A
+ * folder matches under either product name, since installs made before the
+ * repositories were renamed sit under the old one.
+ */
+export function findAbsorbedPlugin(checkout: { directory?: string | null; id?: string | null }): AbsorbedPlugin | null {
+  const directory = checkout.directory?.toLowerCase();
+  return ABSORBED_PLUGINS.find((plugin) => (
+    plugin.id === checkout.id
+    || (!!directory && pluginDirectoryNames(plugin.directory).includes(directory))
+  )) ?? null;
+}

package/src/plugins/auto-update-node.ts

@@ -0,0 +1,114 @@
+import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+
+import { debugLog } from "../utils/debug-log";
+import {
+  runPluginAutoUpdate,
+  startPluginAutoUpdates,
+  type PluginAutoUpdateDeps,
+  type PluginAutoUpdateState,
+  type PluginCheckout,
+} from "./auto-update";
+import type { PluginManager } from "./builtin/plugin-marketplace/store";
+import { checkPluginCompatibility, readPluginManifest } from "./compat";
+import { installedPeerPlugins } from "./host-link";
+import { getPluginCacheDir, getPluginsDir, pluginsMissingHostExports, readPluginCommit } from "./loader";
+import { bunCommand } from "./dependencies";
+
+/**
+ * Automatic plugin updates for a process that can run git and bun: the
+ * terminal, and the desktop's Bun side. The schedule and the rules are in
+ * auto-update.ts; this reads the plugins folder and runs the installer.
+ */
+
+const log = debugLog.createLogger("plugin-updates");
+
+// Loaded on first use: the first pass runs well after startup.
+const installer = () => import("./installer");
+
+function readJson(path: string): Record<string, unknown> | null {
+  try {
+    const value = JSON.parse(readFileSync(path, "utf-8"));
+    return value && typeof value === "object" ? value as Record<string, unknown> : null;
+  } catch {
+    return null;
+  }
+}
+
+async function readCheckouts(): Promise<PluginCheckout[]> {
+  const { installedPluginDirectories, readPluginRemote } = await installer();
+  const pluginsDir = getPluginsDir();
+  return installedPluginDirectories().map((directory) => {
+    const dir = join(pluginsDir, directory);
+    const pkg = readJson(join(dir, "package.json"));
+    const dependencies = pkg?.dependencies;
+    return {
+      directory,
+      id: readPluginManifest(dir).id,
+      repo: existsSync(join(dir, ".git")) ? readPluginRemote(dir) : null,
+      commit: readPluginCommit(dir),
+      version: typeof pkg?.version === "string" ? pkg.version : null,
+      linked: lstatSync(dir, { throwIfNoEntry: false })?.isSymbolicLink() === true,
+      needsGloomberb: checkPluginCompatibility(dir)?.needsGloomberb ?? null,
+      peers: installedPeerPlugins(dir, pluginsDir).map((peer) => peer.directory),
+      hasDependencies: !!dependencies && typeof dependencies === "object" && Object.keys(dependencies).length > 0,
+    };
+  });
+}
+
+function createNodeAutoUpdateDeps(manager: PluginManager): PluginAutoUpdateDeps {
+  return {
+    checkouts: readCheckouts,
+    registry: async () => {
+      const { loadRegistry } = await import("./builtin/plugin-marketplace/feed");
+      const feed = await loadRegistry();
+      return feed.error && feed.plugins.length === 0 ? null : feed.plugins;
+    },
+    remoteHead: async (directory) => (await installer()).readPluginRemoteHead(directory),
+    hasLocalChanges: async (directory) => (await installer()).hasLocalChanges(join(getPluginsDir(), directory)),
+    hasBun: () => bunCommand() !== null,
+    update: (directory, pin) => manager.update(directory, pin),
+    log: (message) => log.info(message),
+  };
+}
+
+const stateFile = () => join(getPluginCacheDir(), "auto-update.json");
+
+function readState(): PluginAutoUpdateState | null {
+  const value = readJson(stateFile());
+  return value && typeof value.checkedAt === "number" && typeof value.hostVersion === "string"
+    ? { checkedAt: value.checkedAt, hostVersion: value.hostVersion }
+    : null;
+}
+
+function writeState(state: PluginAutoUpdateState): void {
+  try {
+    mkdirSync(getPluginCacheDir(), { recursive: true });
+    writeFileSync(stateFile(), JSON.stringify(state));
+  } catch (error) {
+    log.warn(`Could not record the plugin update check: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+export interface NodePluginAutoUpdateOptions {
+  /** The manager the Plugins pane uses in this process, so both update the same way. */
+  manager: PluginManager;
+  /** Read on every pass, so turning the setting off stops the next one. */
+  isEnabled(): boolean | Promise<boolean>;
+  /** Brings the updated plugins into the running session. */
+  onUpdated(directories: string[]): void | Promise<void>;
+}
+
+/** Starts automatic updates of official plugins; returns the function that stops them. */
+export function startNodePluginAutoUpdates(options: NodePluginAutoUpdateOptions): () => void {
+  const deps = createNodeAutoUpdateDeps(options.manager);
+  return startPluginAutoUpdates({
+    isEnabled: options.isEnabled,
+    run: (only) => runPluginAutoUpdate(deps, only),
+    missingHostExports: pluginsMissingHostExports,
+    readState,
+    writeState,
+    onUpdated: options.onUpdated,
+    log: (message) => log.warn(message),
+  });
+}