@jxsuite/studio 4.0.0 → 4.1.0

package/src/services/ai-models.ts

@@ -20,6 +20,16 @@ import { onSettingsChanged } from "./settings/kernel";
 export interface AiModel {
   id: string;
   name: string;
+  /**
+   * Whether the backend says the model can call tools.
+   *
+   * Absent when it did not say, which is the ordinary case for a BYOK provider — only a managed
+   * catalogue knows. `false` is therefore a statement and `undefined` is silence, and no gate may
+   * collapse the two: a Workers AI chat-only model must be labelled, an OpenAI model must not.
+   */
+  toolSupport?: boolean;
+  /** The backend's declared context window in tokens, when it declares one. */
+  contextWindow?: number;
 }
 
 /**
@@ -74,6 +84,23 @@ let proxyCode: AiModelsResponse["code"];
 let proxyProbe: Promise<void> | null = null;
 const probeListeners = new Set<() => void>();
 
+/**
+ * How long a settled probe is trusted before a window refocus re-runs it.
+ *
+ * The probe is one-shot by construction (`proxyProbe ??=`) and the only thing that re-arms it is
+ * the settings subscription below — which never fires for a HOSTED grant, because nothing about it
+ * is stored in this browser. So a Cloudflare grant that lapsed mid-session left every gate showing
+ * the reading it took at boot: the assistant reported itself configured, and every send failed. Ten
+ * minutes is well inside the hour a Cloudflare access token lives.
+ */
+export const PROBE_STALE_MS = 600_000;
+
+/** When the probe last settled (0 = never). The age {@link PROBE_STALE_MS} is measured against. */
+let probeSettledAt = 0;
+
+/** Whether {@link installProbeRefresh} has already registered its listener. */
+let probeRefreshInstalled = false;
+
 /**
  * Drop the cached list and the capability reading.
  *
@@ -93,6 +120,7 @@ export function resetModelCache() {
      would strand every gate on a permanent "unconfigured, unmanaged" reading — ensureProxyProbe
      would no-op forever and the managed option would vanish until a full reload. */
   proxyProbe = null;
+  probeSettledAt = 0;
 }
 
 /** The keys whose value changes what a provider would answer with. */
@@ -117,6 +145,33 @@ export function cachedModels(credentials: AiCredentials): AiModel[] | null {
   return cache && cacheKey === fingerprint(credentials) ? cache : null;
 }
 
+/**
+ * A model's entry in whatever list is cached, by id.
+ *
+ * Deliberately NOT keyed by credentials, unlike {@link cachedModels}. That key exists because
+ * SHOWING one provider's catalogue under another's credentials is a lie about what is available;
+ * asking "what did the backend say about this id" is not — the answer is either recorded or it is
+ * not, and a mismatched key just yields `undefined`, which every caller already has to handle.
+ */
+function cachedModel(id: string): AiModel | undefined {
+  return cache?.find((model) => model.id === id);
+}
+
+/**
+ * Whether the backend said this model can call tools — `undefined` when it said nothing.
+ *
+ * The distinction is the whole point: a chat-only model is a legitimate choice, so this labels and
+ * warns rather than gating, and silence must read as "no opinion" rather than as "no tools".
+ */
+export function modelToolSupport(id: string): boolean | undefined {
+  return cachedModel(id)?.toolSupport;
+}
+
+/** The backend's declared context window for a model, in tokens — `undefined` when it declared none. */
+export function modelContextWindow(id: string): number | undefined {
+  return cachedModel(id)?.contextWindow;
+}
+
 /**
  * Run the capability probe once, repainting `onSettled` when it lands. Idempotent: concurrent and
  * repeated callers share the single in-flight fetch, and every registered host is notified. Probe
@@ -133,12 +188,50 @@ export function ensureProxyProbe(onSettled?: () => void) {
       // Unreachable proxy — the key gate stays up.
     })
     .then(() => {
+      probeSettledAt = Date.now();
       for (const notify of probeListeners) {
         notify();
       }
     });
 }
 
+/**
+ * Re-run the capability probe when it is older than {@link PROBE_STALE_MS} and the backend holds
+ * the credentials. Returns whether it re-armed, so a caller (and a test) can see that it did.
+ *
+ * Managed-only on purpose. A BYOK reading changes only when the stored key does, and the settings
+ * subscription already covers that; a hosted grant expires on a clock this browser cannot see.
+ */
+export function refreshStaleProbe(): boolean {
+  if (!proxyManaged || probeSettledAt === 0 || Date.now() - probeSettledAt < PROBE_STALE_MS) {
+    return false;
+  }
+  proxyProbe = null;
+  probeSettledAt = 0;
+  ensureProxyProbe();
+  return true;
+}
+
+/**
+ * Re-check the probe whenever the window regains focus, which is where a lapsed grant is noticed.
+ *
+ * `focus` rather than a timer: the reading only matters when somebody is looking at Studio, and the
+ * OAuth reconnect the stale reading would have hidden happens in another tab — so coming back IS
+ * the event. Idempotent, and a no-op outside a browser so the module stays importable under a
+ * bare-`bun` runner.
+ */
+export function installProbeRefresh(): void {
+  if (typeof window === "undefined" || probeRefreshInstalled) {
+    return;
+  }
+  probeRefreshInstalled = true;
+  window.addEventListener("focus", () => {
+    refreshStaleProbe();
+  });
+}
+
+installProbeRefresh();
+
 /**
  * Whether the assistant can run at all: a key stored in this browser, or a backend that holds
  * credentials itself (managed cloud platforms, env-keyed dev servers). Every credentials gate must
@@ -263,7 +356,21 @@ export async function fetchAvailableModels(
   proxyManaged = data.managed === true;
   proxyDefaultModel = data.defaultModel ?? "";
   proxyCode = data.code;
-  cache = (data.models || []).map((m) => ({ id: m.id, name: m.name || m.id }));
+  /* Capabilities are kept, not dropped. The backend has reported `toolSupport` all along and the
+     ingest mapped `{id, name}` only, so a Workers AI model that cannot call tools looked exactly
+     like one that can — the agent loop ran, called nothing, and answered as if that were normal.
+     The keys are OMITTED rather than set to undefined: absent means "the backend said nothing",
+     which is a third state both consumers depend on. */
+  cache = (data.models || []).map((m) => {
+    const model: AiModel = { id: m.id, name: m.name || m.id };
+    if (typeof m.contextWindow === "number") {
+      model.contextWindow = m.contextWindow;
+    }
+    if (typeof m.toolSupport === "boolean") {
+      model.toolSupport = m.toolSupport;
+    }
+    return model;
+  });
   cacheKey = key;
   return cache;
 }

package/src/services/context-manager.ts

@@ -12,6 +12,7 @@
  */
 
 import type { createChatState } from "@jxsuite/ai/chat-state";
+import { modelContextWindow } from "./ai-models";
 
 /** Shape of a single entry returned by `chatState.toMessagesArray()`. */
 interface MessageArrayEntry {
@@ -52,7 +53,13 @@ const BUDGET_FRACTION = 0.8;
 const WARN_FRACTION = 0.5;
 
 /**
- * Resolve the context window (tokens) for a model id via longest-prefix match.
+ * Resolve the context window (tokens) for a model id: what the backend reported, else a
+ * longest-prefix match on the table above, else the conservative default.
+ *
+ * The backend's number goes first because the table can only ever know the names it was written
+ * with. Every `@cf/*` model missed it and was budgeted at {@link DEFAULT_CONTEXT_WINDOW}, so a
+ * managed 128k model started dropping the oldest turns at about 25.6k — a fifth of what it could
+ * hold, on the one backend that actually publishes the figure.
  *
  * @param {string | undefined} model
  * @returns {number}
@@ -61,6 +68,10 @@ function contextWindowFor(model: string | undefined): number {
   if (!model) {
     return DEFAULT_CONTEXT_WINDOW;
   }
+  const reported = modelContextWindow(model);
+  if (reported !== undefined && reported > 0) {
+    return reported;
+  }
   const id = model.toLowerCase();
   let best = 0;
   let window = DEFAULT_CONTEXT_WINDOW;

package/src/services/tool-executor.ts

@@ -27,6 +27,7 @@ import type { ToolRegistry } from "@jxsuite/ai/tools";
 
 import type { Tab } from "../tabs/tab";
 import { batchTab, beginBatch, endBatch } from "../tabs/transact";
+import { ensureProxyProbe, resetModelCache } from "./ai-models";
 import { beginTurn, endTurn } from "./ai-writes";
 import { beginToolCall, beginTurnSignal, endTurnSignal } from "./ai-turn-signal";
 
@@ -112,6 +113,7 @@ export async function runAgentLoop({
       const toolCalls = new Map<string, { name: string; arguments: string }>();
       let stopReason = "stop";
       let streamError = null;
+      let streamErrorCode: string | undefined;
 
       for await (const event of streamingClient.streamChat(
         messages,
@@ -147,6 +149,7 @@ export async function runAgentLoop({
           }
           case "error": {
             streamError = event.message;
+            streamErrorCode = event.code;
             break;
           }
           default: {
@@ -158,6 +161,14 @@ export async function runAgentLoop({
       chatState.finishStream(stopReason);
 
       if (streamError) {
+        /* A lapsed hosted grant is the one stream error that makes the app's OWN reading wrong.
+           The probe settles once at boot, so without this every gate keeps offering an assistant
+           that cannot answer, and the send that just failed is the only evidence anyone has. Drop
+           the reading and re-probe, so the next paint carries the Reconnect CTA instead. */
+        if (streamErrorCode === "cf_reconnect_required") {
+          resetModelCache();
+          ensureProxyProbe();
+        }
         chatState.setError(streamError);
         return;
       }

package/src/settings/preferences-accounts.ts

@@ -17,12 +17,31 @@
  *
  * **No secret is ever returned.** A record says whether something is stored and what it is for;
  * printing a token into a list is how a screenshot leaks one.
+ *
+ * **Cloudflare has two spellings, and this file used to know only one.** On a platform that brokers
+ * the connection (Jx Cloud), there is no local token to enumerate — `getCfToken()` is empty by
+ * design — so the row said "Not connected" to every hosted user, named no account, and offered a
+ * Disconnect that cleared nothing server-side. The hosted state comes from the PAL instead, cached
+ * here because a template must not start a fetch on every repaint.
  */
 
 import { clearGithubToken, githubTokenLocation, githubTokenStored } from "../github/github-auth";
 import { clearCfConnection, getCfAccountId, getCfToken } from "../services/cf-settings";
 import { clearAiProvider, getBaseUrl, hasOpenAiKey } from "../services/ai-settings";
-import { preferredModel } from "../services/ai-models";
+import { preferredModel, resetModelCache } from "../services/ai-models";
+import { getPlatform, hasPlatform } from "../platform";
+import type { CfConnection } from "../types";
+
+/** One thing a row can do besides existing. */
+export interface AccountAction {
+  /** Stable key — the button's `data-action`, so a test names an intent rather than a label. */
+  id: string;
+  label: string;
+  /** Spectrum `variant`; omitted for the default treatment. */
+  variant?: string;
+  /** Do it. Async ones repaint the sheet when they settle. */
+  run: () => void | Promise<void>;
+}
 
 /** One stored credential, as the Accounts section renders it. */
 export interface AccountRecord {
@@ -35,6 +54,178 @@ export interface AccountRecord {
   connected: boolean;
   /** Forget it. Idempotent: revoking a disconnected account is a no-op, not an error. */
   revoke: () => void;
+  /**
+   * What this row offers, when a plain Disconnect is not the whole story.
+   *
+   * Absent on the rows whose only verb is "forget it", which is every locally stored credential. A
+   * brokered Cloudflare connection has three more — reconnect a lapsed grant, choose an account,
+   * connect for the first time — and none of them is expressible as `revoke`.
+   */
+  actions?: AccountAction[];
+}
+
+// ─── The brokered Cloudflare connection ──────────────────────────────────────
+
+/** What the broker last said, or "checking" before it has been asked. */
+let _cfState: CfConnection | null | "checking" = "checking";
+
+/** The in-flight read, so a repaint during one does not start a second. */
+let _cfInFlight: Promise<void> | null = null;
+
+/**
+ * Whether the platform brokers the Cloudflare connection rather than holding a pasted token.
+ *
+ * Keyed on `cfConnect` — the hosted OAuth flow — because that is the member whose presence means
+ * "there is a connection this app did not store locally".
+ */
+export function platformBrokersCf(): boolean {
+  return hasPlatform() && Boolean(getPlatform().cfConnect);
+}
+
+/**
+ * Re-read the brokered connection and announce it. Always refetches; the Accounts section runs it
+ * when it is shown and after every action, because the answer changes server-side.
+ */
+export async function refreshCfConnection(): Promise<void> {
+  if (!platformBrokersCf()) {
+    return;
+  }
+  _cfInFlight ??= (async () => {
+    try {
+      _cfState = (await getPlatform().cfConnection?.()) ?? null;
+    } catch {
+      /* An unreachable broker is not a connection. The row says "not connected", which is what the
+         app can act on; the error itself belongs to whatever surface made the call the user asked
+         for, not to a list that repaints itself. */
+      _cfState = null;
+    }
+    _cfInFlight = null;
+    notifyCredentialsChanged();
+  })();
+  await _cfInFlight;
+}
+
+/** Kick the first read, once. Safe to call from a template — later paints are no-ops. */
+export function ensureCfConnection(): void {
+  if (platformBrokersCf() && _cfState === "checking" && !_cfInFlight) {
+    void refreshCfConnection();
+  }
+}
+
+/**
+ * Forget the cached broker answer.
+ *
+ * Called when Preferences opens, and that is the point: the row would otherwise paint the answer
+ * from the LAST visit — an hour-old "Connected — Acme" over a grant that has since lapsed — and
+ * only correct itself when the re-read landed. Saying "checking" while it checks is the honest
+ * version of the same half-second.
+ */
+export function resetCfConnectionCache(): void {
+  _cfState = "checking";
+  _cfInFlight = null;
+}
+
+/** Run the hosted flow, then re-read. The models cache goes because the AI gate keys on it too. */
+async function hostedConnect(): Promise<void> {
+  const outcome = await getPlatform().cfConnect?.();
+  if (outcome?.status === "connected" && !outcome.connection.accountId) {
+    /* Dynamically, and this is the load-bearing half: the picker imports THIS module for
+       `notifyCredentialsChanged`, so a static import here would close the cycle. */
+    const { openCfAccountPicker } = await import("../ui/cf-account-picker");
+    await openCfAccountPicker();
+  }
+  resetModelCache();
+  await refreshCfConnection();
+}
+
+/** The brokered row — five states, and each one names the next move. */
+function brokeredCloudflareRecord(): AccountRecord {
+  const disconnect: AccountAction = {
+    id: "disconnect",
+    label: "Disconnect",
+    run: async () => {
+      await getPlatform().cfDisconnect?.();
+      resetModelCache();
+      await refreshCfConnection();
+    },
+    variant: "negative",
+  };
+  const connect = (label: string): AccountAction => ({
+    id: label === "Connect" ? "connect" : "reconnect",
+    label,
+    run: hostedConnect,
+    variant: "accent",
+  });
+  const base = { id: "cloudflare", label: "Cloudflare", revoke: () => {} };
+
+  if (_cfState === "checking") {
+    return { ...base, actions: [], connected: false, detail: "Checking your connection…" };
+  }
+  if (!_cfState?.connected) {
+    return {
+      ...base,
+      actions: [connect("Connect")],
+      connected: false,
+      detail: "Not connected. Connecting publishes this site and runs the assistant on Workers AI.",
+    };
+  }
+  const revoke = () => {
+    void disconnect.run();
+  };
+  if (_cfState.needsReconnect) {
+    return {
+      ...base,
+      actions: [connect("Reconnect"), disconnect],
+      connected: true,
+      detail: "Connection expired. Reconnect to keep publishing and the assistant working.",
+      revoke,
+    };
+  }
+  if (_cfState.needsAccount || !_cfState.accountId) {
+    return {
+      ...base,
+      actions: [
+        {
+          id: "choose-account",
+          label: "Choose account",
+          run: async () => {
+            const { openCfAccountPicker } = await import("../ui/cf-account-picker");
+            if (await openCfAccountPicker()) {
+              resetModelCache();
+              await refreshCfConnection();
+            }
+          },
+          variant: "accent",
+        },
+        disconnect,
+      ],
+      connected: true,
+      detail: "Connected, but no account is chosen yet — publishing and the assistant need one.",
+      revoke,
+    };
+  }
+  return {
+    ...base,
+    actions: [disconnect],
+    connected: true,
+    detail: `Connected — ${_cfState.accountName ?? _cfState.accountId}.`,
+    revoke,
+  };
+}
+
+/** The locally stored row: a pasted API token, on desktop and the dev server. */
+function localCloudflareRecord(): AccountRecord {
+  const cfToken = getCfToken();
+  const cfAccount = getCfAccountId();
+  return {
+    connected: Boolean(cfToken),
+    detail: cfToken
+      ? `Connected${cfAccount ? ` — account ${cfAccount}` : ""}.`
+      : "Not connected. Publishing will ask when it needs it.",
+    id: "cloudflare",
+    label: "Cloudflare",
+    revoke: clearCfConnection,
+  };
 }
 
 /**
@@ -45,8 +236,6 @@ export interface AccountRecord {
  */
 export function listAccounts(): AccountRecord[] {
   const githubToken = githubTokenStored();
-  const cfToken = getCfToken();
-  const cfAccount = getCfAccountId();
   const model = preferredModel();
   const endpoint = getBaseUrl();
   return [
@@ -70,15 +259,7 @@ export function listAccounts(): AccountRecord[] {
       connected: hasOpenAiKey(),
       revoke: clearAiProvider,
     },
-    {
-      id: "cloudflare",
-      label: "Cloudflare",
-      detail: cfToken
-        ? `Connected${cfAccount ? ` — account ${cfAccount}` : ""}.`
-        : "Not connected. Publishing will ask when it needs it.",
-      connected: Boolean(cfToken),
-      revoke: clearCfConnection,
-    },
+    platformBrokersCf() ? brokeredCloudflareRecord() : localCloudflareRecord(),
   ];
 }
 

package/src/settings/preferences-dialog.ts

@@ -38,7 +38,15 @@ import { createManagedConnect } from "../ui/ai-managed-connect";
 import { activeRegistry } from "../commands/active-registry";
 import { shortcutReference, SCOPE_LABELS } from "../commands/reference";
 import { chordFromEvent } from "../commands/keymap";
-import { listAccounts, notifyCredentialsChanged, revokeAccount } from "./preferences-accounts";
+import {
+  ensureCfConnection,
+  listAccounts,
+  notifyCredentialsChanged,
+  platformBrokersCf,
+  refreshCfConnection,
+  resetCfConnectionCache,
+  revokeAccount,
+} from "./preferences-accounts";
 import { applyKeybindingOverrides, rebindCommand, resetKeybinding } from "./preferences-keymap";
 import { overlayRegion } from "../ui/regions";
 
@@ -97,6 +105,19 @@ function credentialsChanged(): void {
   repaint();
 }
 
+/**
+ * Showing a section is a chance to find out it is stale.
+ *
+ * Only Accounts has anything to re-read: the brokered Cloudflare connection lives on the server, so
+ * a grant that lapsed while Preferences was closed — or while the author was in Keyboard — would
+ * otherwise be reported from a cache taken before it did.
+ */
+function sectionShown(): void {
+  if (_section === "accounts" && platformBrokersCf()) {
+    void refreshCfConnection().then(repaint);
+  }
+}
+
 /** The shared credentials form — draft state lives inside the form's closure. */
 const credsForm = createAiCredentialsForm({
   intro: html`
@@ -144,7 +165,52 @@ function assistantTpl(): TemplateResult {
   return html`<div class="prefs-assistant">${managedConnect.render()} ${credsForm.render()}</div>`;
 }
 
+/**
+ * The buttons on one row.
+ *
+ * A record that declares `actions` decides its own verbs; everything else keeps the original rule —
+ * a connected credential offers Disconnect and a disconnected one offers nothing. The async ones
+ * repaint when they settle, because a hosted Reconnect is a round trip through a Cloudflare popup
+ * and the row must not still be reading "expired" when it comes back.
+ */
+function accountActionsTpl(account: ReturnType<typeof listAccounts>[number]) {
+  if (account.actions) {
+    return account.actions.map(
+      (action) => html`
+        <sp-button
+          size="s"
+          data-action=${action.id}
+          variant=${action.variant ?? nothing}
+          treatment=${action.variant === "negative" ? "outline" : nothing}
+          @click=${() => {
+            void Promise.resolve(action.run()).finally(repaint);
+          }}
+        >
+          ${action.label}
+        </sp-button>
+      `,
+    );
+  }
+  return account.connected
+    ? html`
+        <sp-button
+          size="s"
+          variant="negative"
+          treatment="outline"
+          @click=${() => {
+            revokeAccount(account.id);
+            repaint();
+          }}
+        >
+          Disconnect
+        </sp-button>
+      `
+    : nothing;
+}
+
 function accountsTpl(): TemplateResult {
+  // First paint asks the broker what it holds; the answer arrives as a credentials-changed repaint.
+  ensureCfConnection();
   return html`
     <div class="prefs-accounts">
       ${listAccounts().map(
@@ -154,23 +220,7 @@ function accountsTpl(): TemplateResult {
               <span class="prefs-account-label">${account.label}</span>
               <span class="prefs-account-detail">${account.detail}</span>
             </div>
-            ${
-              account.connected
-                ? html`
-                    <sp-button
-                      size="s"
-                      variant="negative"
-                      treatment="outline"
-                      @click=${() => {
-                        revokeAccount(account.id);
-                        repaint();
-                      }}
-                    >
-                      Disconnect
-                    </sp-button>
-                  `
-                : nothing
-            }
+            <div class="prefs-account-actions">${accountActionsTpl(account)}</div>
           </div>
         `,
       )}
@@ -449,15 +499,21 @@ function sectionBodyTpl(): TemplateResult {
  * @param section One of {@link PREFERENCES_SECTIONS}' ids. An unknown id falls back to Appearance.
  */
 export function openPreferences(section?: string): Promise<null> {
+  /* Opening is a fresh look, so nothing may be reported from the last one: a brokered Cloudflare
+     grant can lapse between visits, and a row that repaints the previous answer first is stating
+     something it has no reason to believe. */
+  resetCfConnectionCache();
   _section = section !== undefined && isPreferencesSection(section) ? section : _section;
   if (_close) {
     repaint();
+    sectionShown();
     return Promise.resolve(null);
   }
   _section =
     section !== undefined && isPreferencesSection(section) ? section : DEFAULT_PREFERENCES_SECTION;
   credsForm.startEdit();
   resetKeyboardState();
+  sectionShown();
   return showDialog<null>(
     (done) => {
       let wrapperEl: HTMLElement | null = null;
@@ -500,6 +556,7 @@ export function openPreferences(section?: string): Promise<null> {
                         // First chord pressed on the author's NEXT visit.
                         resetKeyboardState();
                         repaint();
+                        sectionShown();
                       }}
                     >
                       ${candidate.title}

package/src/types.ts

@@ -14,7 +14,9 @@ import type {
 import type {
   AppInfo,
   AssetCapabilities,
+  CfAccountSummary,
   CfConnection,
+  CfConnectOutcome,
   CodeServiceResult,
   ComponentMeta,
   DataConnectionsResponse,
@@ -54,7 +56,9 @@ export type {
   AiModelInfo,
   AiModelsResponse,
   AppInfo,
+  CfAccountSummary,
   CfConnection,
+  CfConnectOutcome,
   CodeServiceResult,
   ComponentMeta,
   ComponentSlotMeta,
@@ -612,14 +616,34 @@ export interface StudioPlatform {
     head?: string;
     base?: string;
   }) => Promise<{ url: string; number: number }>;
-  /** Current Cloudflare connection state, when the platform can broker one. */
+  /**
+   * Current Cloudflare connection state, when the platform can broker one. See {@link CfConnection}
+   * for what null, `{connected: false}` and `needsReconnect` each mean — they are three different
+   * states and the UI says a different sentence for each.
+   */
   cfConnection?: () => Promise<CfConnection | null>;
   /**
    * Interactively connect a Cloudflare account (hosted OAuth on the cloud platform). Local
    * platforms omit it — the publish UI collects an API token instead and verifies via
    * cfConnection.
-   */
-  cfConnect?: () => Promise<CfConnection | null>;
+   *
+   * Resolves a {@link CfConnectOutcome} rather than a connection, because "connected" is only one of
+   * four endings: a blocked popup navigates the whole page (`redirect`), a closed popup is a
+   * cancellation, and a passed deadline is a timeout. Rejects only when the flow actually failed —
+   * a relayed OAuth error, or a success the platform could not confirm. Resolves null only where
+   * there is no DOM to open a popup in.
+   */
+  cfConnect?: () => Promise<CfConnectOutcome | null>;
+  /**
+   * Every Cloudflare account the connected grant can reach. Backs the account picker a
+   * multi-account user needs before publishing: the broker stores one account id per connection,
+   * and until one is chosen every Cloudflare-backed call answers `cf_account_required`.
+   */
+  cfAccounts?: () => Promise<CfAccountSummary[]>;
+  /** Store the chosen account on the brokered connection (the picker's commit). */
+  cfSelectAccount?: (account: { id: string; name?: string }) => Promise<void>;
+  /** Forget the brokered connection and revoke its tokens upstream. */
+  cfDisconnect?: () => Promise<void>;
   /**
    * Allowlisted Cloudflare API passthrough (accounts, Pages projects and deployments). The backend
    * injects credentials — an OAuth token on the cloud platform, the user's pasted API token locally