gloomberb 0.16.4 → 0.16.6

package/src/remote/confirm-change.tsx

@@ -0,0 +1,85 @@
+import { useEffect } from "react";
+import { Box, useUiHost } from "../ui";
+import { ConfirmDialog } from "../components/ui/confirm-dialog";
+import { KeyValueRow } from "../components/ui/display";
+import { useViewport } from "../react/input";
+import type { DialogApi, PromptContext } from "../ui/dialog";
+import type { RemoteChangePrompt } from "./types";
+
+const WIDTH = 52;
+const MIN_WIDTH = 24;
+/** The terminal dialog's border and padding around its content. */
+const TERMINAL_FRAME_COLUMNS = 8;
+const LABEL_WIDTH = 11;
+/** The change asks on its own, maybe mid-keystroke: Enter or `y` typed just before it opened do not approve it. */
+const KEY_GRACE_MS = 600;
+
+export function RemoteChangeDialog({
+  resolve,
+  dismiss,
+  dialogId,
+  prompt,
+  signal,
+  keyGraceMs = KEY_GRACE_MS,
+}: PromptContext<boolean> & { prompt: RemoteChangePrompt; signal?: AbortSignal; keyGraceMs?: number }) {
+  const viewport = useViewport();
+  const terminal = useUiHost().kind === "opentui";
+  // A narrow terminal gets a narrower dialog rather than a clipped one.
+  const width = terminal ? Math.max(MIN_WIDTH, Math.min(WIDTH, viewport.width - TERMINAL_FRAME_COLUMNS)) : WIDTH;
+
+  useEffect(() => {
+    if (!signal) return;
+    const decline = () => resolve(false);
+    if (signal.aborted) {
+      decline();
+      return;
+    }
+    signal.addEventListener("abort", decline, { once: true });
+    return () => signal.removeEventListener("abort", decline);
+  }, [resolve, signal]);
+
+  return (
+    <ConfirmDialog
+      resolve={resolve}
+      dismiss={dismiss}
+      dialogId={dialogId}
+      title={prompt.title}
+      body={(
+        <Box flexDirection="column" width={width}>
+          {prompt.lines.map((line) => (
+            <KeyValueRow
+              key={line.label}
+              label={line.label}
+              value={line.value}
+              width={width}
+              labelWidth={LABEL_WIDTH}
+            />
+          ))}
+        </Box>
+      )}
+      confirmLabel={prompt.confirmLabel}
+      confirmVariant={prompt.destructive ? "danger" : "primary"}
+      width={width}
+      keyGraceMs={keyGraceMs}
+    />
+  );
+}
+
+/**
+ * Asks the person to approve one change a remote caller asked for. Resolves
+ * true only on Add or Remove; Cancel, Esc, a closed dialog or an aborted
+ * `signal` resolve false.
+ */
+export async function confirmRemoteChange(
+  dialog: DialogApi,
+  prompt: RemoteChangePrompt,
+  signal?: AbortSignal,
+): Promise<boolean> {
+  if (signal?.aborted) return false;
+  const answer = await dialog.prompt<boolean>({
+    closeOnClickOutside: false,
+    closeOnEscape: true,
+    content: (context) => <RemoteChangeDialog {...context} prompt={prompt} signal={signal} />,
+  }).catch(() => false);
+  return answer === true;
+}

package/src/remote/controller-utils.ts

@@ -18,11 +18,18 @@ export function ok<T>(data: T, rev?: string, state?: RemoteIncludedState): Remot
   };
 }
 
+/** A failure with its own code, such as `unsupported` for an operation this app cannot run. */
+export class RemoteOperationError extends Error {
+  constructor(readonly code: string, message: string) {
+    super(message);
+  }
+}
+
 export function fail(code: string, error: unknown): RemoteControlResponse {
   return {
     ok: false,
     error: {
-      code,
+      code: error instanceof RemoteOperationError ? error.code : code,
       message: error instanceof Error ? error.message : String(error),
     },
   };

package/src/remote/controller.ts

@@ -19,9 +19,13 @@ import {
 } from "../plugins/builtin/custom-view";
 import { findPaneInstance, getPlacedPaneInstanceIds, type PaneInstanceConfig, resolvePaneInstance } from "../types/config";
 import type { DesktopWindowBridge } from "../types/desktop-window";
+import { settleTypedListingKey } from "../tickers/listing-venues";
+import { isSharedExchangeCode, parsePublicTickerKey, typedExchangeCode } from "../utils/exchanges";
 import { applyJsonPatch } from "./json-patch";
 import { revisionFor } from "./revision";
 import type {
+  RemoteCallContext,
+  RemoteChangePrompt,
   RemoteControlRequest,
   RemoteControlResponse,
   RemoteJsonPatchOperation,
@@ -31,7 +35,7 @@ import type {
 import type { RemoteUiRegistry } from "./semantic-tree";
 import { commandBarResultsFromNodes, isCommandBarInputNode } from "./command-bar";
 import { findCommandBarResult, findMatchingUiNode } from "./matching";
-import { REMOTE_AGENT_HELP, remoteControlSchema } from "./schema";
+import { REMOTE_AGENT_HELP, REMOTE_OPERATIONS, remoteControlSchema } from "./schema";
 import {
   fail,
   mutationSummary,
@@ -39,8 +43,16 @@ import {
   ok,
   optionalNumber,
   optionalString,
+  RemoteOperationError,
   stringInput,
 } from "./controller-utils";
+import {
+  PANE_SCREENSHOT_MAX_BYTES,
+  PANE_SCREENSHOT_MAX_EDGE,
+  PANE_SCREENSHOT_MIN_WIDTH,
+  paneScreenshotScale,
+  type CapturePane,
+} from "./pane-screenshot";
 import {
   buildGridDockRoot,
   regionToDockPosition,
@@ -51,6 +63,14 @@ import { createRemoteResources } from "./resources";
 import { dismissTopmostDialog, isDialogOpen as isAnyDialogOpen } from "../ui/dialog-stack";
 import { asRecord } from "../utils/guards";
 import { runAutomated } from "../telemetry/usage-counts";
+import {
+  applyWatchlistChange,
+  declinedWatchlistResult,
+  describeWatchlistPlan,
+  planWatchlistChange,
+  unchangedWatchlistResult,
+  watchlistChangePrompt,
+} from "./watchlist";
 
 interface AppRemoteControllerOptions {
   dispatch: Dispatch<AppAction>;
@@ -63,8 +83,20 @@ interface AppRemoteControllerOptions {
   isDialogOpen?: () => boolean;
   /** Closes the dialog on top as Esc would; false when none is open. */
   closeTopmostDialog?: () => boolean;
+  /**
+   * Asks the person in the app to approve a change to their data; false when
+   * they decline or `signal` aborts. Without it such operations refuse.
+   */
+  confirmChange?: (prompt: RemoteChangePrompt, signal?: AbortSignal) => Promise<boolean>;
+  /** Paints one pane of this window as a PNG; absent where there are no pixels (the TUI). */
+  capturePane?: CapturePane;
 }
 
+/** Operations whose dry run resolves what they would change instead of echoing the input. */
+const PLANNED_OPERATIONS = new Set(["watchlist.add", "watchlist.remove"]);
+/** Reads change nothing, so their answer carries no layout or command-bar state. */
+const READ_OPERATIONS = new Set(REMOTE_OPERATIONS.filter((entry) => entry.sideEffectLevel === "none").map((entry) => entry.id));
+
 // A command with a wizard closes the bar and opens its form, so every call says whether one is open.
 const DEFAULT_MUTATION_INCLUDE: RemoteStateInclude[] = ["app", "layout", "panes", "commandBar", "form"];
 const MAX_MARKET_DATA_SEARCH_RESULTS = 20;
@@ -97,6 +129,8 @@ export function createAppRemoteController({
   afterMutation = () => {},
   isDialogOpen = isAnyDialogOpen,
   closeTopmostDialog = dismissTopmostDialog,
+  confirmChange,
+  capturePane,
 }: AppRemoteControllerOptions) {
   const { buildIncludedState, getResource, patchTarget } = createRemoteResources({
     dispatch,
@@ -111,8 +145,26 @@ export function createAppRemoteController({
     return mutationSummary(getState(), extra);
   };
 
-  const queryMarketData = async (request: RemoteMarketDataRequest): Promise<unknown> => {
+  /**
+   * The listing a request names, a code that names several venues (7203:TSE,
+   * or 7203 with exchange TSE) read as the one its symbol trades on, as every
+   * command reads it.
+   */
+  const settledListing = async (rawSymbol: string, rawExchange: string | undefined) => {
+    const symbol = normalizedMarketDataSymbol(rawSymbol);
+    const exchange = normalizedOptionalExchange(rawExchange);
+    const typed = exchange && isSharedExchangeCode(exchange) && !parsePublicTickerKey(symbol).exchange ? `${symbol}:${exchange}` : symbol;
+    if (!isSharedExchangeCode(typedExchangeCode(typed))) return { symbol, exchange };
+    const settled = (await settleTypedListingKey(typed, {
+      store: pluginRegistry.tickerRepository,
+      dataProvider: pluginRegistry.marketData,
+    })).toUpperCase();
+    return settled === typed ? { symbol, exchange } : { symbol: settled, exchange: parsePublicTickerKey(settled).exchange };
+  };
+
+  const queryMarketData = async (named: RemoteMarketDataRequest): Promise<unknown> => {
     const marketData = pluginRegistry.marketData;
+    const request = "symbol" in named ? { ...named, ...await settledListing(named.symbol, named.exchange) } : named;
     switch (request.operation) {
       case "search":
         return (await marketData.search(requiredMarketDataText(request.query, "query")))
@@ -264,9 +316,90 @@ export function createAppRemoteController({
     return getAfterMutationSummary({ invokedNode: node, result });
   };
 
+  /** The focused pane, or the one asked for, as the window draws it now. */
+  const screenshotPane = async (input: Record<string, unknown>): Promise<unknown> => {
+    if (!capturePane) {
+      throw new RemoteOperationError(
+        "unsupported",
+        "Pane screenshots need the Gloom desktop app: the terminal (TUI) app draws text, not pixels. Read the pane's content instead.",
+      );
+    }
+    const width = input.width;
+    if (width !== undefined && (
+      typeof width !== "number" || !Number.isInteger(width) || width < PANE_SCREENSHOT_MIN_WIDTH || width > PANE_SCREENSHOT_MAX_EDGE
+    )) {
+      throw new Error(`width must be a whole number of pixels from ${PANE_SCREENSHOT_MIN_WIDTH} to ${PANE_SCREENSHOT_MAX_EDGE}.`);
+    }
+    const state = getState();
+    const layout = state.config.layout;
+    const asked = optionalString(input, "paneId");
+    const instance = asked
+      ? resolvePaneInstance(layout, asked)
+      : state.focusedPaneId ? findPaneInstance(layout, state.focusedPaneId) : undefined;
+    if (!instance) {
+      throw new Error(asked ? `No pane "${asked}" is open in this layout. Read app://panes for the open ones.` : "No pane is focused. Pass paneId.");
+    }
+    if ((layout.detached ?? []).some((entry) => entry.instanceId === instance.instanceId)) {
+      throw new Error(`Pane "${instance.instanceId}" is in its own window; dock it to capture it.`);
+    }
+    const shot = await capturePane({
+      instanceId: instance.instanceId,
+      scaleFor: (screen) => paneScreenshotScale(screen, width as number | undefined),
+      maxBytes: PANE_SCREENSHOT_MAX_BYTES,
+      minWidth: PANE_SCREENSHOT_MIN_WIDTH,
+    });
+    return {
+      pane: {
+        instanceId: instance.instanceId,
+        paneId: instance.paneId,
+        ...(instance.title ? { title: instance.title } : {}),
+      },
+      image: { mimeType: "image/png", data: shot.pngBase64, width: shot.width, height: shot.height, bytes: shot.bytes },
+      screen: shot.screen,
+      ...(shot.reduced ? { reduced: true } : {}),
+    };
+  };
+
+  const workflowDeps = () => ({
+    dataProvider: pluginRegistry.marketData,
+    tickerRepository: pluginRegistry.tickerRepository,
+    pluginRegistry,
+    dispatch,
+    getState,
+  });
+
+  /**
+   * Adds or removes one ticker on a personal watchlist, after the person
+   * approves that exact change in the app. A caller that already showed them
+   * the dry run's summary and got a yes passes its confirmKey instead.
+   */
+  const changeWatchlist = async (
+    operation: string,
+    input: Record<string, unknown>,
+    dryRun: boolean | undefined,
+    context: RemoteCallContext,
+  ): Promise<unknown> => {
+    const action = operation === "watchlist.add" ? "add" : "remove";
+    const plan = await planWatchlistChange(action, {
+      symbol: stringInput(input, "symbol"),
+      exchange: optionalString(input, "exchange"),
+      watchlist: optionalString(input, "watchlist"),
+    }, workflowDeps());
+    if (dryRun) return describeWatchlistPlan(plan);
+    if (!plan.changes) return unchangedWatchlistResult(plan);
+    if (context.confirmed !== plan.confirmKey) {
+      if (!confirmChange) throw new Error("This window cannot ask for confirmation, so nothing changed.");
+      if (!await confirmChange(watchlistChangePrompt(plan), context.signal)) return declinedWatchlistResult(plan);
+    }
+    return runAutomated(() => applyWatchlistChange(plan, workflowDeps()));
+  };
+
   // What remote control opens is automation, not the user opening a function.
-  const call = (operation: string, rawInput: unknown, dryRun?: boolean): Promise<unknown> => (
-    runAutomated(() => callOperation(operation, rawInput, dryRun))
+  // A watchlist change waits on the person, so only its write is automated.
+  const call = (operation: string, rawInput: unknown, dryRun: boolean | undefined, context: RemoteCallContext): Promise<unknown> => (
+    PLANNED_OPERATIONS.has(operation)
+      ? changeWatchlist(operation, asRecord(rawInput), dryRun, context)
+      : runAutomated(() => callOperation(operation, rawInput, dryRun))
   );
 
   const callOperation = async (operation: string, rawInput: unknown, dryRun?: boolean): Promise<unknown> => {
@@ -307,6 +440,8 @@ export function createAppRemoteController({
         pluginRegistry.hidePane(paneId);
         return getAfterMutationSummary({ affectedPaneIds: [paneId] });
       }
+      case "pane.screenshot":
+        return screenshotPane(input);
       case "pane.createFromTemplate":
         await pluginRegistry.createPaneFromTemplateAsync(
           stringInput(input, "templateId"),
@@ -499,7 +634,8 @@ export function createAppRemoteController({
     }
   };
 
-  const handle = async (request: RemoteControlRequest): Promise<RemoteControlResponse> => {
+  /** `context` comes from in-process callers only; the local endpoint never passes one. */
+  const handle = async (request: RemoteControlRequest, context: RemoteCallContext = {}): Promise<RemoteControlResponse> => {
     try {
       switch (request.type) {
         case "help":
@@ -513,8 +649,9 @@ export function createAppRemoteController({
         case "data":
           return ok(await queryMarketData(request));
         case "call": {
-          const data = await call(request.operation, request.input, request.dryRun);
-          return ok(data, undefined, buildIncludedState(request.include, request.dryRun ? [] : DEFAULT_MUTATION_INCLUDE));
+          const data = await call(request.operation, request.input, request.dryRun, context);
+          const defaults = request.dryRun || READ_OPERATIONS.has(request.operation) ? [] : DEFAULT_MUTATION_INCLUDE;
+          return ok(data, undefined, buildIncludedState(request.include, defaults));
         }
         case "patch": {
           const target = patchTarget(request.resource);

package/src/remote/pane-screenshot.ts

@@ -0,0 +1,47 @@
+/**
+ * pane.screenshot: one pane as a PNG, painted from what the window shows now.
+ * The bounds keep the image legible for an assistant and small enough for one
+ * Gloom Cloud socket frame (the terminal relay carries it to the MCP).
+ */
+
+/** Neither side of the image is longer; assistants shrink larger images anyway. */
+export const PANE_SCREENSHOT_MAX_EDGE = 1600;
+/** The narrowest image a caller can ask for, and the floor when shrinking to fit the byte cap. */
+export const PANE_SCREENSHOT_MIN_WIDTH = 200;
+/** The PNG never exceeds this; a larger paint is shrunk until it fits. */
+export const PANE_SCREENSHOT_MAX_BYTES = 512 * 1024;
+/** Pixels per screen point by default: as sharp as a Retina screen. */
+const DEFAULT_SCALE = 2;
+const MAX_SCALE = 3;
+
+export interface PaneScreenshotRequest {
+  instanceId: string;
+  /** Device pixels per CSS pixel to paint a pane of this on-screen size at. */
+  scaleFor(screen: { width: number; height: number }): number;
+  maxBytes: number;
+  minWidth: number;
+}
+
+interface PaneScreenshot {
+  pngBase64: string;
+  width: number;
+  height: number;
+  bytes: number;
+  /** The pane's size on screen, in CSS pixels. */
+  screen: { width: number; height: number };
+  /** Shrunk below the asked size so the PNG fits `maxBytes`. */
+  reduced: boolean;
+}
+
+/** Paints one pane of this window. Only renderers with pixels (the desktop app) have one. */
+export type CapturePane = (request: PaneScreenshotRequest) => Promise<PaneScreenshot>;
+
+/**
+ * The paint scale for a pane of `screen` size: `width` pixels wide when asked,
+ * otherwise twice its on-screen size, within the long-edge bound either way.
+ */
+export function paneScreenshotScale(screen: { width: number; height: number }, width?: number): number {
+  const longest = Math.max(1, screen.width, screen.height);
+  const wanted = width === undefined ? DEFAULT_SCALE : width / Math.max(1, screen.width);
+  return Math.min(wanted, MAX_SCALE, PANE_SCREENSHOT_MAX_EDGE / longest);
+}

package/src/remote/schema.ts

@@ -7,6 +7,11 @@ import type {
   RemoteSideEffectLevel,
   RemoteWriteTier,
 } from "./types";
+import {
+  PANE_SCREENSHOT_MAX_BYTES,
+  PANE_SCREENSHOT_MAX_EDGE,
+  PANE_SCREENSHOT_MIN_WIDTH,
+} from "./pane-screenshot";
 
 export const REMOTE_RESOURCES: RemoteResourceSchema[] = [
   { uri: "app://snapshot", description: "Current app snapshot including layout, focus, panes, command bar, and plugin/capability catalogs. app.activePanel is deprecated and always \"left\"; read app.focusedPaneId." },
@@ -49,6 +54,21 @@ function objectSchema(
 }
 
 const paneIdInput = objectSchema({ paneId: requiredStringSchema }, ["paneId"]);
+const watchlistChangeInput = objectSchema({
+  symbol: { type: "string", minLength: 1, maxLength: 32, description: "Ticker symbol, such as MSFT." },
+  exchange: {
+    type: "string",
+    minLength: 1,
+    maxLength: 16,
+    description: "Listing exchange, for a symbol that trades in several places, such as NASDAQ or LSE.",
+  },
+  watchlist: {
+    type: "string",
+    minLength: 1,
+    maxLength: 120,
+    description: "Watchlist id or name from app://config. Without it, the default watchlist: the first personal one.",
+  },
+}, ["symbol"]);
 
 export const REMOTE_OPERATIONS: RemoteOperationSchema[] = [
   op(
@@ -113,6 +133,28 @@ export const REMOTE_OPERATIONS: RemoteOperationSchema[] = [
   op("pane.show", "Show or focus a pane type.", "{ paneId: string }", "local-write", paneIdInput),
   op("pane.focus", "Focus a pane instance or pane type.", "{ paneId: string }", "local-write", paneIdInput),
   op("pane.close", "Close a pane instance or pane type.", "{ paneId: string }", "local-write", paneIdInput),
+  {
+    ...op(
+      "pane.screenshot",
+      "Capture one pane as a PNG, as it looks on screen now: the focused pane, or paneId (an instance id or pane type from app://panes). "
+        + "It only reads what is already on the person's own screen. Desktop app only: the terminal (TUI) app draws text, not pixels. "
+        + `The image is twice the pane's on-screen size by default, at most ${PANE_SCREENSHOT_MAX_EDGE} px on its longer side and ${PANE_SCREENSHOT_MAX_BYTES / 1024} KB; `
+        + `width asks for another width (${PANE_SCREENSHOT_MIN_WIDTH} to ${PANE_SCREENSHOT_MAX_EDGE} px). `
+        + "A pane in its own window, behind another tab or in another layout is not drawn here and cannot be captured.",
+      "{ paneId?: string, width?: number }",
+      "none",
+      objectSchema({
+        paneId: { type: "string", minLength: 1, description: "Pane instance id or pane type. Defaults to the focused pane." },
+        width: {
+          type: "integer",
+          minimum: PANE_SCREENSHOT_MIN_WIDTH,
+          maximum: PANE_SCREENSHOT_MAX_EDGE,
+          description: "Image width in pixels; the height keeps the pane's proportions.",
+        },
+      }),
+    ),
+    returnsImage: true,
+  },
   op(
     "pane.createFromTemplate",
     "Open a pane from a registered template. It only opens the pane: it adds nothing to a portfolio or watchlist.",
@@ -151,7 +193,7 @@ export const REMOTE_OPERATIONS: RemoteOperationSchema[] = [
   ),
   op(
     "ticker.navigate",
-    "Navigate a ticker into the best available ticker research target.",
+    "Show any ticker in the ticker research pane the user is on, or the best available one, as in \"switch to MSFT\".",
     "{ symbol: string, sourcePaneId?: string }",
     "local-write",
     objectSchema({ symbol: requiredStringSchema, sourcePaneId: stringSchema }, ["symbol"]),
@@ -170,7 +212,8 @@ export const REMOTE_OPERATIONS: RemoteOperationSchema[] = [
   ),
   op(
     "ticker.select",
-    "Select a ticker in a target pane.",
+    "Move the cursor of a portfolio or watchlist pane to a ticker on its list, so the panes that follow the list show it. "
+      + "To show any ticker in a ticker pane, use ticker.navigate.",
     "{ symbol: string, paneId?: string }",
     "local-write",
     objectSchema({ symbol: requiredStringSchema, paneId: stringSchema }, ["symbol"]),
@@ -182,6 +225,24 @@ export const REMOTE_OPERATIONS: RemoteOperationSchema[] = [
     "local-write",
     objectSchema({ tabId: requiredStringSchema, paneId: stringSchema }, ["tabId"]),
   ),
+  op(
+    "watchlist.add",
+    "Add a ticker to one of the person's own watchlists. The app asks them first, naming the list, ticker and exchange. "
+      + "The result says what changed: added, already on the list, or declined. Team watchlists and portfolios are refused.",
+    "{ symbol: string, exchange?: string, watchlist?: string }",
+    "local-write",
+    watchlistChangeInput,
+    "user-data",
+  ),
+  op(
+    "watchlist.remove",
+    "Remove a ticker from one of the person's own watchlists. The app asks them first, naming the list, ticker and exchange. "
+      + "The result says what changed: removed, not on the list, or declined. Team watchlists and portfolios are refused.",
+    "{ symbol: string, exchange?: string, watchlist?: string }",
+    "local-write",
+    watchlistChangeInput,
+    "user-data",
+  ),
   op(
     "layout.switch",
     "Switch active layout by index.",
@@ -386,6 +447,8 @@ export const REMOTE_AGENT_HELP = {
     "While a dialog is open (form.open or form.otherDialogOpen), app.openCommandBar and app.search fail; close a form or confirm with { role: 'form', action: 'cancel' }, and any dialog on top with app.closeDialog.",
     "A form with covered: true has another dialog over it, such as a listing picker or a sign-in; its controls wait until that one is answered or closed with app.closeDialog.",
     "Pane settings open in their own dialog, not as command-bar rows; change one with pane.setSetting, read them from app://pane-settings/{paneId}, and close the dialog with app.closeDialog.",
+    "watchlist.add and watchlist.remove wait while the person answers a confirmation in the app and return what changed; with dryRun they return what would change without asking.",
+    "pane.screenshot returns the pane's PNG as base64 in image.data, with its pixel size; the terminal (TUI) app answers that it needs the desktop app.",
     "Use ui.invokeMatching only after checking app-level operations; it is intentionally generic and depends on visible semantic controls.",
   ],
 };

package/src/remote/types.ts

@@ -62,6 +62,31 @@ export type RemoteControlRequest =
     include?: RemoteStateInclude[];
   };
 
+/**
+ * What an in-process caller adds to a request. Never read from the request
+ * itself, so a client of the local endpoint cannot claim a confirmation.
+ */
+export interface RemoteCallContext {
+  /**
+   * The `confirmKey` of the change the person already approved in this app
+   * for this call, from the operation's dry run (Ask Gloom, the terminal
+   * relay). The operation then writes without asking again, and asks anyway
+   * when what it would change no longer has that key.
+   */
+  confirmed?: string;
+  /** The caller gave up: a confirmation the operation opened closes as declined. */
+  signal?: AbortSignal;
+}
+
+/** One change the app asks the person to approve before it writes their data. */
+export interface RemoteChangePrompt {
+  title: string;
+  lines: Array<{ label: string; value: string }>;
+  confirmLabel: string;
+  /** A change that takes something away. */
+  destructive?: boolean;
+}
+
 export interface RemoteIncludedState {
   rev: string;
   included: RemoteStateInclude[];
@@ -151,6 +176,11 @@ export interface RemoteOperationSchema {
   writeTier: RemoteWriteTier;
   requiresConfirmation?: boolean;
   dryRun?: boolean;
+  /**
+   * The result carries a PNG in `image` ({ mimeType, data, width, height,
+   * bytes }). Text-only tool channels (Ask Gloom) leave such an operation out.
+   */
+  returnsImage?: boolean;
 }
 
 /** Stable operation metadata suitable for advertising outside the process. */