gloomberb 0.15.2 → 0.15.3

package/src/brokers/signed-in/catalog.ts

@@ -0,0 +1,129 @@
+/**
+ * The signed-in brokers Gloom Cloud offers, as last seen. Add Broker, the
+ * Brokers pane, onboarding and the adapter read it synchronously. It refreshes
+ * at startup and when Add Broker or onboarding opens, and the last list is kept
+ * in plugin state (which, unlike the desktop view's resource cache, survives a
+ * restart everywhere) so the directory still lists them offline. The desktop's
+ * Bun half never fetches; it picks up the list the view saved.
+ */
+import type { PluginPersistence } from "../../types/plugin";
+import { listSignedInBrokers, type SignedInBroker } from "./client";
+
+const FRESH_MS = 5 * 60_000;
+/** How often a known list looks for a newer saved one. */
+const RECHECK_MS = 60_000;
+const STATE_KEY = "signed-in-brokers";
+const SCHEMA_VERSION = 1;
+/** One empty list, so a React snapshot of "nothing yet" is stable. */
+const NONE: SignedInBroker[] = [];
+
+function isSignedInBroker(value: unknown): value is SignedInBroker {
+  const entry = value as Partial<SignedInBroker> | null;
+  return !!entry
+    && typeof entry.id === "string"
+    && typeof entry.name === "string"
+    && !!entry.capabilities
+    && typeof entry.capabilities === "object";
+}
+
+function readBrokers(value: unknown): SignedInBroker[] | null {
+  return Array.isArray(value) ? value.filter(isSignedInBroker) : null;
+}
+
+export interface SignedInBrokerCatalog {
+  attach(persistence: PluginPersistence): void;
+  reset(): void;
+  get(): SignedInBroker[];
+  find(brokerId: string): SignedInBroker | null;
+  refresh(options?: { force?: boolean }): Promise<void>;
+  subscribe(listener: () => void): () => void;
+}
+
+export function createSignedInBrokerCatalog(
+  load: () => Promise<{ connectors: SignedInBroker[] }>,
+  now: () => number = Date.now,
+): SignedInBrokerCatalog {
+  let persistence: PluginPersistence | null = null;
+  // Null until a list is known, so a store attached after the first read still counts.
+  let brokers: SignedInBroker[] | null = null;
+  let fetchedAt = 0;
+  let checkedAt = 0;
+  let inFlight: Promise<void> | null = null;
+  const listeners = new Set<() => void>();
+
+  const notify = () => {
+    for (const listener of listeners) listener();
+  };
+
+  // Another process on the same store (the desktop view, for its Bun half)
+  // may have saved a newer list, so a known list looks again once a minute.
+  const ensureLoaded = (): SignedInBroker[] => {
+    if (brokers && now() - checkedAt < RECHECK_MS) return brokers;
+    checkedAt = now();
+    const saved = persistence?.getState<{ brokers?: unknown; fetchedAt?: unknown }>(STATE_KEY, {
+      schemaVersion: SCHEMA_VERSION,
+    });
+    const restored = readBrokers(saved?.brokers);
+    const savedAt = typeof saved?.fetchedAt === "number" ? saved.fetchedAt : 0;
+    if (restored && (!brokers || savedAt > fetchedAt)) {
+      brokers = restored;
+      fetchedAt = savedAt;
+    }
+    return brokers ?? NONE;
+  };
+
+  return {
+    attach(next) {
+      persistence = next;
+      if (!brokers) ensureLoaded();
+    },
+    reset() {
+      persistence = null;
+      brokers = null;
+      fetchedAt = 0;
+      checkedAt = 0;
+      inFlight = null;
+    },
+    get: ensureLoaded,
+    find(brokerId) {
+      return ensureLoaded().find((broker) => broker.id === brokerId) ?? null;
+    },
+    refresh(options = {}) {
+      ensureLoaded();
+      if (inFlight) return inFlight;
+      if (!options.force && brokers && now() - fetchedAt < FRESH_MS) return Promise.resolve();
+      inFlight = load()
+        .then((response) => {
+          const next = readBrokers(response?.connectors);
+          if (!next) return;
+          brokers = next;
+          fetchedAt = now();
+          notify();
+          persistence?.setState(STATE_KEY, { brokers: next, fetchedAt }, { schemaVersion: SCHEMA_VERSION });
+        })
+        // Offline or Cloud down: the last list stays, and the next open retries.
+        .catch(() => {})
+        .finally(() => {
+          inFlight = null;
+        });
+      return inFlight;
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+  };
+}
+
+const catalog = createSignedInBrokerCatalog(listSignedInBrokers);
+
+export const attachSignedInBrokerPersistence = catalog.attach;
+export const resetSignedInBrokerCatalog = catalog.reset;
+/** The last known list; empty until the first fetch or a restored copy. */
+export const getSignedInBrokers = catalog.get;
+export const findSignedInBroker = catalog.find;
+/** Fetches the list unless it is under five minutes old. Never rejects. */
+export const refreshSignedInBrokers = catalog.refresh;
+export const subscribeSignedInBrokers = catalog.subscribe;

package/src/brokers/signed-in/client.ts

@@ -0,0 +1,54 @@
+/**
+ * Gloom Cloud's broker connections, under `/brokers`. Brokers whose connection
+ * Cloud holds ("signed-in brokers") are described by the backend, so a new one
+ * appears here without an app release.
+ */
+import { apiClient } from "../../api-client";
+import type { BrokerOrderType } from "../../types/trading";
+
+export interface SignedInBrokerCapabilities {
+  history: boolean;
+  executions: boolean;
+  orders: false | { mode: "review" | "direct"; types: BrokerOrderType[] };
+  /** Connecting Gloom replaces this broker's link to other AI apps. */
+  singleConnection: boolean;
+  /** Shown before connecting, e.g. an account the user must create first. */
+  signupNote?: string;
+}
+
+export interface SignedInBroker {
+  id: string;
+  name: string;
+  capabilities: SignedInBrokerCapabilities;
+}
+
+export interface SignedInBrokerConnection {
+  broker: string;
+  status: "connected" | "reauth_required" | "not_connected";
+  scopes: string[];
+  canTrade: boolean;
+  accountIds: string[];
+  connectedAt: string | null;
+  refreshedAt: string | null;
+  syncedAt: string | null;
+}
+
+/** Public: the list does not depend on the user, so Add Broker can show it signed out. */
+export function listSignedInBrokers(): Promise<{ connectors: SignedInBroker[] }> {
+  return apiClient.brokerRequest("connectors", "");
+}
+
+export function fetchSignedInBrokerConnection(brokerId: string): Promise<SignedInBrokerConnection> {
+  return apiClient.brokerRequest(brokerId, "");
+}
+
+export function startSignedInBrokerConnect(
+  brokerId: string,
+  write: boolean,
+): Promise<{ connectUrl: string; code: string; expiresAt: string }> {
+  return apiClient.brokerRequest(brokerId, "/connect", { method: "POST", body: { write } });
+}
+
+export function disconnectSignedInBroker(brokerId: string): Promise<{ disconnected: boolean }> {
+  return apiClient.brokerRequest(brokerId, "", { method: "DELETE" });
+}

package/src/brokers/signed-in/connect.ts

@@ -0,0 +1,69 @@
+/**
+ * Connecting a signed-in broker from Add Broker and onboarding. The connection
+ * lives in the Gloom account, so a device needs one profile per broker:
+ * connecting again syncs the profile it already has.
+ */
+import { ApiRequestError } from "../../api-client/errors";
+import type { AppConfig, BrokerInstanceConfig } from "../../types/config";
+import { findSignedInBroker } from "./catalog";
+import { disconnectSignedInBroker, type SignedInBroker } from "./client";
+import { SIGNED_IN_BROKER_TYPE, isSignedInBrokerProfile, signedInBrokerId } from "./profile";
+import { requestBrokerSignIn } from "./sign-in-dialog";
+
+export function findSignedInBrokerProfile(
+  instances: readonly BrokerInstanceConfig[],
+  brokerId: string,
+): BrokerInstanceConfig | undefined {
+  return instances.find((instance) => isSignedInBrokerProfile(instance) && signedInBrokerId(instance) === brokerId);
+}
+
+/** The broker a signed-in profile connects, known or not to the last connector list. */
+export function signedInBrokerForProfile(instance: BrokerInstanceConfig, fallbackName: string): SignedInBroker {
+  const id = signedInBrokerId(instance);
+  return findSignedInBroker(id) ?? {
+    id,
+    name: fallbackName,
+    capabilities: { history: false, executions: false, orders: false, singleConnection: false },
+  };
+}
+
+export interface ConnectSignedInBrokerDeps<T> {
+  getConfig(): AppConfig;
+  createBrokerInstance(brokerType: string, label: string, values: Record<string, unknown>): Promise<BrokerInstanceConfig>;
+  syncBrokerInstance(instanceId: string): Promise<T>;
+  /** Opens the connect dialog; replaced in tests. */
+  requestSignIn?: (broker: SignedInBroker) => Promise<boolean>;
+}
+
+/**
+ * Asks the user to connect `broker`, then syncs its profile, creating it the
+ * first time. Resolves null when the broker was not connected.
+ */
+export async function connectSignedInBrokerProfile<T>(
+  broker: SignedInBroker,
+  deps: ConnectSignedInBrokerDeps<T>,
+): Promise<{ instance: BrokerInstanceConfig; synced: T } | null> {
+  const connected = await (deps.requestSignIn ?? requestBrokerSignIn)(broker);
+  if (!connected) return null;
+  const instance = findSignedInBrokerProfile(deps.getConfig().brokerInstances, broker.id)
+    ?? await deps.createBrokerInstance(SIGNED_IN_BROKER_TYPE, broker.name, { connectionMode: broker.id, broker: broker.id });
+  return { instance, synced: await deps.syncBrokerInstance(instance.id) };
+}
+
+/**
+ * Disconnects the Gloom account's connection behind a signed-in profile before
+ * the profile goes. Already gone is fine; signed out of Gloom, the account
+ * keeps the broker, which the caller reports as `stillConnected`.
+ */
+export async function disconnectSignedInProfile(instance: BrokerInstanceConfig): Promise<{ stillConnected: boolean }> {
+  if (!isSignedInBrokerProfile(instance)) return { stillConnected: false };
+  try {
+    await disconnectSignedInBroker(signedInBrokerId(instance));
+    return { stillConnected: false };
+  } catch (error) {
+    if (error instanceof ApiRequestError && error.status === 404) return { stillConnected: false };
+    if (error instanceof ApiRequestError && error.status === 401) return { stillConnected: true };
+    throw error;
+  }
+}
+

package/src/brokers/signed-in/profile.ts

@@ -0,0 +1,18 @@
+/**
+ * How a signed-in broker profile is stored: the built-in adapter's type, with
+ * the backend broker in `connectionMode` (cloud sync keeps it, unlike `config`)
+ * and again in `config.broker`.
+ */
+import type { BrokerInstanceConfig } from "../../types/config";
+
+export const SIGNED_IN_BROKER_TYPE = "signed-in";
+
+export function isSignedInBrokerProfile(instance: BrokerInstanceConfig): boolean {
+  return instance.brokerType === SIGNED_IN_BROKER_TYPE;
+}
+
+/** The backend broker a profile connects, e.g. "ibkr". */
+export function signedInBrokerId(instance: BrokerInstanceConfig): string {
+  if (instance.connectionMode) return instance.connectionMode;
+  return typeof instance.config.broker === "string" ? instance.config.broker : "";
+}

package/src/brokers/signed-in/sign-in-dialog.tsx

@@ -0,0 +1,187 @@
+/**
+ * The dialog that connects a signed-in broker, plus the request bridge that
+ * lets the command bar, the Brokers pane and onboarding open it. Those run
+ * outside the React tree or in the desktop view, which is also where the
+ * browser hand-off has to happen, so the broker adapter never opens it.
+ */
+import { useEffect, useRef, useState } from "react";
+import { apiClient, type AuthUser } from "../../api-client";
+import { SignInCodePanel } from "../../components/sign-in-code-panel";
+import { t, tf } from "../../i18n";
+import { useAppLanguage } from "../../i18n/react";
+import { useViewport } from "../../react/input";
+import { colors } from "../../theme/colors";
+import { Box, Text, TextAttributes } from "../../ui";
+import { useDialog, useDialogKeyboard, type PromptContext } from "../../ui/dialog";
+import { isPlainKey } from "../../utils/keyboard";
+import { DeviceSignInDialog } from "../../plugins/builtin/cloud/device-signin-dialog";
+import type { SignedInBroker } from "./client";
+import {
+  BrokerSignInController,
+  runBrokerSignIn,
+  type BrokerSignInOutcome,
+  type BrokerSignInSnapshot,
+} from "./sign-in";
+
+function signInStatus(snapshot: BrokerSignInSnapshot, broker: SignedInBroker): { text: string; color: string } {
+  switch (snapshot.phase) {
+    case "connected":
+      return { text: t("Connected"), color: colors.positive };
+    case "error":
+    case "signed-out":
+      return { text: snapshot.error ?? t("Something went wrong."), color: colors.negative };
+    case "waiting":
+      return snapshot.error
+        ? { text: t(snapshot.error), color: colors.warning }
+        : { text: tf("Waiting for {broker}...", { broker: broker.name }), color: colors.textDim };
+    default:
+      return { text: t("Contacting Gloom..."), color: colors.textDim };
+  }
+}
+
+function BrokerSignInDialog({
+  resolve,
+  dismiss,
+  broker,
+  write,
+}: PromptContext<BrokerSignInOutcome> & { broker: SignedInBroker; write: boolean }) {
+  useAppLanguage();
+  const { height: termHeight } = useViewport();
+  const controllerRef = useRef<BrokerSignInController | null>(null);
+  if (!controllerRef.current) controllerRef.current = new BrokerSignInController(broker, write);
+  const controller = controllerRef.current;
+  const [snapshot, setSnapshot] = useState(controller.getSnapshot());
+
+  useEffect(() => {
+    const unsubscribe = controller.subscribe(setSnapshot);
+    controller.start();
+    return () => {
+      unsubscribe();
+      controller.cancel();
+    };
+  }, [controller]);
+
+  // Close after a beat so "Connected" is visible; enter skips the wait. Signed
+  // out closes at once, for the host to sign in to Gloom.
+  useEffect(() => {
+    if (snapshot.phase === "signed-out") {
+      resolve("signed-out");
+      return;
+    }
+    if (snapshot.phase !== "connected") return;
+    const closeTimer = setTimeout(() => resolve("connected"), 900);
+    return () => clearTimeout(closeTimer);
+  }, [resolve, snapshot.phase]);
+
+  useDialogKeyboard((event) => {
+    event.stopPropagation();
+    if (event.name === "enter" || event.name === "return") {
+      if (snapshot.phase === "connected") resolve("connected");
+    } else if (isPlainKey(event, "r") && snapshot.phase !== "connected") {
+      controller.start();
+    } else if (event.name === "escape") {
+      dismiss();
+    }
+  });
+
+  const note = broker.capabilities.signupNote
+    ?? (broker.capabilities.singleConnection
+      ? tf("Other AI apps linked to {broker} get disconnected. Connect them to Gloom instead.", { broker: broker.name })
+      : null);
+  // Title, spacing, note, and footer take about eleven rows around the panel.
+  const panelHeight = Math.max(4, termHeight - (note ? 12 : 10));
+
+  return (
+    <Box flexDirection="column" alignItems="center">
+      <Box height={1}>
+        <Text fg={colors.textBright} attributes={TextAttributes.BOLD}>
+          {tf("Connect {broker}", { broker: broker.name })}
+        </Text>
+      </Box>
+      <Box height={1}>
+        <Text fg={colors.textDim}>{t("Open the link and enter the code there.")}</Text>
+      </Box>
+      <Box height={1} />
+      <SignInCodePanel
+        url={snapshot.connectUrl}
+        code={snapshot.code}
+        status={signInStatus(snapshot, broker)}
+        height={panelHeight}
+        shortcutScope="broker-signin:browser"
+      />
+      {note && (
+        <>
+          <Box height={1} />
+          <Box height={1}>
+            <Text fg={colors.textMuted}>{note}</Text>
+          </Box>
+        </>
+      )}
+      <Box height={1} />
+      <Box height={1}>
+        <Text fg={colors.textMuted}>{t("r for a new code · esc to cancel")}</Text>
+      </Box>
+    </Box>
+  );
+}
+
+export interface BrokerSignInRequest {
+  broker: SignedInBroker;
+  /** Ask for trading as well as reading. Defaults to whether the broker takes orders. */
+  write?: boolean;
+  resolve: (connected: boolean) => void;
+}
+
+const requestListeners = new Set<(request: BrokerSignInRequest) => void>();
+
+/**
+ * Connects a signed-in broker, signing in to Gloom first when needed.
+ * Resolves true once the broker is connected, false when the user cancels or
+ * no dialog host is mounted.
+ */
+export function requestBrokerSignIn(broker: SignedInBroker, options: { write?: boolean } = {}): Promise<boolean> {
+  if (requestListeners.size === 0) return Promise.resolve(false);
+  return new Promise((resolve) => {
+    const write = options.write ?? Boolean(broker.capabilities.orders);
+    for (const listener of requestListeners) listener({ broker, write, resolve });
+  });
+}
+
+export function BrokerSignInDialogHost() {
+  const dialog = useDialog();
+  const openRef = useRef(false);
+
+  useEffect(() => {
+    const listener = (request: BrokerSignInRequest) => {
+      if (openRef.current) {
+        request.resolve(false);
+        return;
+      }
+      openRef.current = true;
+      // The broker connection belongs to the Gloom account, so there must be one.
+      void runBrokerSignIn(request.broker, request.write, {
+        isSignedIn: () => apiClient.isSignedIn(),
+        signInToGloom: async () => !!await dialog.prompt<AuthUser | undefined>({
+          size: "full",
+          content: (context: unknown) => <DeviceSignInDialog {...(context as PromptContext<AuthUser | undefined>)} />,
+        }),
+        connectBroker: async (broker, write) => await dialog.prompt<BrokerSignInOutcome>({
+          size: "full",
+          content: (context: unknown) => (
+            <BrokerSignInDialog {...(context as PromptContext<BrokerSignInOutcome>)} broker={broker} write={write} />
+          ),
+        }) ?? "cancelled",
+      })
+        .then(request.resolve, () => request.resolve(false))
+        .finally(() => {
+          openRef.current = false;
+        });
+    };
+    requestListeners.add(listener);
+    return () => {
+      requestListeners.delete(listener);
+    };
+  }, [dialog]);
+
+  return null;
+}

package/src/brokers/signed-in/sign-in.ts

@@ -0,0 +1,178 @@
+/**
+ * Connecting a signed-in broker: Gloom Cloud hands out a link and a short code,
+ * the user opens the link, types the code, and signs in to the broker there.
+ * The code is what ties the browser to this app, so a link someone else started
+ * cannot attach their brokerage to this account. The connection itself lives in
+ * the Cloud account, shared by every device and by the user's agents.
+ */
+import { ApiRequestError } from "../../api-client/errors";
+import {
+  fetchSignedInBrokerConnection,
+  startSignedInBrokerConnect,
+  type SignedInBroker,
+  type SignedInBrokerConnection,
+} from "./client";
+
+/** "signed-out": Gloom refused the session, so the dialog host signs in again. */
+export type BrokerSignInPhase = "starting" | "waiting" | "connected" | "signed-out" | "error";
+
+export interface BrokerSignInSnapshot {
+  phase: BrokerSignInPhase;
+  connectUrl: string | null;
+  code: string | null;
+  /** A transient poll failure while waiting, or why starting failed. */
+  error: string | null;
+}
+
+export interface BrokerSignInIo {
+  start(brokerId: string, write: boolean): Promise<{ connectUrl: string; code: string; expiresAt: string }>;
+  fetchConnection(brokerId: string): Promise<Pick<SignedInBrokerConnection, "status">>;
+  now(): number;
+  delay(ms: number): Promise<void>;
+}
+
+const POLL_INTERVAL_MS = 2_000;
+const RETRY_MAX_MS = 30_000;
+/** Used when the expiry is missing or unreadable, so polling can never run forever. */
+const DEFAULT_CODE_TTL_MS = 15 * 60_000;
+
+const defaultIo: BrokerSignInIo = {
+  start: (brokerId, write) => startSignedInBrokerConnect(brokerId, write),
+  fetchConnection: (brokerId) => fetchSignedInBrokerConnection(brokerId),
+  now: () => Date.now(),
+  delay: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+};
+
+function describeStartError(error: unknown, broker: SignedInBroker): string {
+  if (error instanceof ApiRequestError && error.status === 404) return `${broker.name} is not available right now.`;
+  return "Can't reach Gloom. Retrying...";
+}
+
+/**
+ * When a code stops working. An expiry this device's clock already sees as
+ * past (the clock runs fast) counts as missing, or every code would expire
+ * the moment it arrived.
+ */
+function codeDeadline(expiresAt: string, now: number): number {
+  const parsed = Date.parse(expiresAt);
+  return Number.isFinite(parsed) && parsed > now ? parsed : now + DEFAULT_CODE_TTL_MS;
+}
+
+export class BrokerSignInController {
+  private readonly io: BrokerSignInIo;
+  private readonly listeners = new Set<(snapshot: BrokerSignInSnapshot) => void>();
+  private generation = 0;
+  private snapshot: BrokerSignInSnapshot = { phase: "starting", connectUrl: null, code: null, error: null };
+
+  constructor(
+    private readonly broker: SignedInBroker,
+    /** Ask for trading as well as reading when the broker offers it. */
+    private readonly write: boolean,
+    io: Partial<BrokerSignInIo> = {},
+  ) {
+    this.io = { ...defaultIo, ...io };
+  }
+
+  getSnapshot(): BrokerSignInSnapshot {
+    return this.snapshot;
+  }
+
+  subscribe(listener: (snapshot: BrokerSignInSnapshot) => void): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  /** Starts, or restarts with a fresh code. Safe to call repeatedly. */
+  start(): void {
+    const generation = ++this.generation;
+    void this.run(generation);
+  }
+
+  cancel(): void {
+    this.generation += 1;
+  }
+
+  private update(next: Partial<BrokerSignInSnapshot>): void {
+    this.snapshot = { ...this.snapshot, ...next };
+    for (const listener of this.listeners) listener(this.snapshot);
+  }
+
+  private async run(generation: number): Promise<void> {
+    const stale = () => this.generation !== generation;
+    let retryMs = POLL_INTERVAL_MS;
+    // Each iteration is one code: start, poll until connected, and loop again
+    // when the code expired so the link refreshes instead of dead-ending.
+    while (!stale()) {
+      this.update({ phase: "starting", connectUrl: null, code: null, error: null });
+      let started: Awaited<ReturnType<BrokerSignInIo["start"]>>;
+      try {
+        started = await this.io.start(this.broker.id, this.write);
+      } catch (error) {
+        if (stale()) return;
+        // A session Gloom no longer accepts (expired, or signed out elsewhere) needs a new sign-in.
+        if (error instanceof ApiRequestError && error.status === 401) {
+          this.update({ phase: "signed-out", error: "Sign in to Gloom first." });
+          return;
+        }
+        this.update({ phase: "error", error: describeStartError(error, this.broker) });
+        // An unknown broker will not fix itself by retrying.
+        if (error instanceof ApiRequestError && error.status === 404) return;
+        await this.io.delay(retryMs);
+        retryMs = Math.min(retryMs * 2, RETRY_MAX_MS);
+        continue;
+      }
+      if (stale()) return;
+      retryMs = POLL_INTERVAL_MS;
+      this.update({ phase: "waiting", connectUrl: started.connectUrl, code: started.code, error: null });
+      const deadline = codeDeadline(started.expiresAt, this.io.now());
+      // At least one poll per code, so the next code is never asked for at once.
+      do {
+        await this.io.delay(POLL_INTERVAL_MS);
+        if (stale()) return;
+        try {
+          // Connected is enough: a user who declined trading still gets a read-only connection.
+          if ((await this.io.fetchConnection(this.broker.id)).status === "connected") {
+            if (!stale()) this.update({ phase: "connected", error: null });
+            this.generation += 1;
+            return;
+          }
+          if (this.snapshot.error) this.update({ error: null });
+        } catch {
+          if (!stale()) this.update({ error: "Connection problem, retrying..." });
+        }
+      } while (!stale() && this.io.now() < deadline);
+    }
+  }
+}
+
+/** How one showing of the connect dialog ended. */
+export type BrokerSignInOutcome = "connected" | "cancelled" | "signed-out";
+
+export interface BrokerSignInSteps {
+  isSignedIn(): boolean;
+  /** The Gloom device sign-in; true once signed in. */
+  signInToGloom(): Promise<boolean>;
+  connectBroker(broker: SignedInBroker, write: boolean): Promise<BrokerSignInOutcome>;
+}
+
+/**
+ * Connects `broker`, signing in to Gloom first when there is no session. A
+ * session kept on this device that Gloom no longer accepts only shows once the
+ * connect starts, so that signs in and tries the broker once more.
+ */
+export async function runBrokerSignIn(
+  broker: SignedInBroker,
+  write: boolean | undefined,
+  steps: BrokerSignInSteps,
+): Promise<boolean> {
+  if (!steps.isSignedIn() && !await steps.signInToGloom()) return false;
+  // Trading is asked for only where the broker takes orders from Gloom.
+  const scope = write ?? Boolean(broker.capabilities.orders);
+  let outcome = await steps.connectBroker(broker, scope);
+  if (outcome === "signed-out" && await steps.signInToGloom()) {
+    outcome = await steps.connectBroker(broker, scope);
+  }
+  return outcome === "connected";
+}