gloomberb 0.16.3 → 0.16.4

package/src/plugins/builtin/cloud/terminal-relay/grants.ts

@@ -0,0 +1,137 @@
+import type { PluginPersistence } from "../../../../types/plugin";
+
+/**
+ * Which remote assistants may control this terminal. Asked once per
+ * assistant (a Gloom Cloud key or a signed-in client): "Always allow" and
+ * "Deny" are kept with the profile, "Allow for this session" lasts until the
+ * app quits. Revoking in Account Management, revoking the key or
+ * disconnecting the client in Cloud settings forgets the decision.
+ */
+export type AssistantDecision = "always" | "session" | "deny";
+
+export interface AssistantGrant {
+  clientId: string;
+  name: string;
+  decision: AssistantDecision;
+  decidedAt: number;
+  lastUsedAt: number | null;
+}
+
+const GRANTS_STATE_KEY = "terminal-relay:grants";
+const DEVICE_STATE_KEY = "terminal-relay:device";
+const MAX_GRANTS = 50;
+
+function isGrant(value: unknown): value is AssistantGrant {
+  if (!value || typeof value !== "object") return false;
+  const record = value as Record<string, unknown>;
+  return typeof record.clientId === "string"
+    && typeof record.name === "string"
+    && (record.decision === "always" || record.decision === "deny")
+    && typeof record.decidedAt === "number";
+}
+
+function randomDeviceId(): string {
+  const bytes = new Uint8Array(16);
+  globalThis.crypto.getRandomValues(bytes);
+  return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+export class TerminalRelayGrants {
+  private persistence: PluginPersistence | null = null;
+  private stored = new Map<string, AssistantGrant>();
+  private readonly session = new Map<string, AssistantGrant>();
+  private readonly listeners = new Set<() => void>();
+  private listed: AssistantGrant[] = [];
+
+  attach(persistence: PluginPersistence): void {
+    this.persistence = persistence;
+    const raw = persistence.getState<unknown>(GRANTS_STATE_KEY);
+    this.stored = new Map(
+      (Array.isArray(raw) ? raw : [])
+        .filter(isGrant)
+        .map((grant) => [grant.clientId, { ...grant, lastUsedAt: grant.lastUsedAt ?? null }]),
+    );
+    this.emit();
+  }
+
+  detach(): void {
+    this.persistence = null;
+    this.stored.clear();
+    this.session.clear();
+    this.emit();
+  }
+
+  get attached(): boolean {
+    return this.persistence !== null;
+  }
+
+  /** A random id for this profile, created once; nothing about the machine is in it. */
+  deviceId(): string | null {
+    if (!this.persistence) return null;
+    const stored = this.persistence.getState<{ id?: unknown }>(DEVICE_STATE_KEY);
+    if (stored && typeof stored.id === "string" && /^[a-f0-9]{32}$/.test(stored.id)) return stored.id;
+    const id = randomDeviceId();
+    this.persistence.setState(DEVICE_STATE_KEY, { id });
+    return id;
+  }
+
+  decision(clientId: string): AssistantDecision | null {
+    return this.session.get(clientId)?.decision ?? this.stored.get(clientId)?.decision ?? null;
+  }
+
+  decide(clientId: string, name: string, decision: AssistantDecision, now = Date.now()): void {
+    const grant: AssistantGrant = { clientId, name, decision, decidedAt: now, lastUsedAt: null };
+    if (decision === "session") {
+      this.session.set(clientId, grant);
+      this.stored.delete(clientId);
+    } else {
+      this.session.delete(clientId);
+      this.stored.set(clientId, grant);
+    }
+    this.persist();
+  }
+
+  markUsed(clientId: string, now = Date.now()): void {
+    const grant = this.session.get(clientId) ?? this.stored.get(clientId);
+    if (!grant) return;
+    grant.lastUsedAt = now;
+    this.emit();
+  }
+
+  /** Forgets an assistant, so its next call asks again. */
+  forget(clientId: string): void {
+    const had = this.session.delete(clientId) || this.stored.has(clientId);
+    this.stored.delete(clientId);
+    if (had) this.persist();
+  }
+
+  /** The same array until something changes, so React can subscribe to it. */
+  list(): AssistantGrant[] {
+    return this.listed;
+  }
+
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  private persist(): void {
+    const kept = [...this.stored.values()]
+      .sort((left, right) => right.decidedAt - left.decidedAt)
+      .slice(0, MAX_GRANTS);
+    this.stored = new Map(kept.map((grant) => [grant.clientId, grant]));
+    this.persistence?.setState(GRANTS_STATE_KEY, kept);
+    this.emit();
+  }
+
+  private emit(): void {
+    this.listed = [...this.session.values(), ...this.stored.values()]
+      .map((grant) => ({ ...grant }))
+      .sort((left, right) => (right.lastUsedAt ?? right.decidedAt) - (left.lastUsedAt ?? left.decidedAt));
+    for (const listener of this.listeners) listener();
+  }
+}
+
+export const terminalRelayGrants = new TerminalRelayGrants();

package/src/plugins/builtin/cloud/terminal-relay/host.tsx

@@ -0,0 +1,81 @@
+import { useEffect, useRef, useSyncExternalStore } from "react";
+import { apiClient } from "../../../../api-client";
+import { useRemoteControlHandler } from "../../../../remote/app-host";
+import { useAppActive } from "../../../../state/app/activity";
+import { useOptionalDialog } from "../../../../ui/dialog";
+import { VERSION } from "../../../../version";
+import { TerminalRelayClient, type TerminalRelaySocket } from "./client";
+import { TerminalRelayEngine } from "./engine";
+import { terminalRelayGrants } from "./grants";
+import { recordRelayActivity } from "./indicator";
+import { dialogRelayPrompts } from "./prompts";
+
+/** What kind of app this is and what to call it in Cloud settings and tool results. */
+export interface TerminalRelayDevice {
+  kind: "desktop" | "tui";
+  name: string;
+}
+
+const ACTIVE_PING_MS = 30_000;
+
+const cloudSocket: TerminalRelaySocket = {
+  subscribeConnection: (listener) => apiClient.subscribeSocketConnection(listener),
+  subscribeCloudEvent: (type, listener) => apiClient.subscribeCloudEvent(type, listener),
+  sendFrame: (frame) => apiClient.sendSocketFrame(frame),
+  serverOffers: (feature) => apiClient.socketServerOffers(feature),
+};
+
+/**
+ * Lets a remote assistant connected to the Gloom Cloud MCP drive this
+ * terminal. Mounted once per app window that owns the layout; renders
+ * nothing itself (the prompts open as dialogs, the chip is a status widget).
+ * Off while the Gloom Cloud plugin is off.
+ */
+export function TerminalRelayHost({ device }: { device: TerminalRelayDevice | undefined }) {
+  const handle = useRemoteControlHandler();
+  const dialog = useOptionalDialog();
+  const appActive = useAppActive();
+  const attached = useSyncExternalStore(
+    (listener) => terminalRelayGrants.subscribe(listener),
+    () => terminalRelayGrants.attached,
+    () => false,
+  );
+  const clientRef = useRef<TerminalRelayClient | null>(null);
+  const kind = device?.kind;
+  const name = device?.name;
+
+  useEffect(() => {
+    if (!handle || !dialog || !kind || !name || !attached) return;
+    const engine = new TerminalRelayEngine({
+      handle,
+      send: (frame) => apiClient.sendSocketFrame(frame),
+      grants: terminalRelayGrants,
+      prompts: dialogRelayPrompts(dialog),
+      onActivity: recordRelayActivity,
+    });
+    const client = new TerminalRelayClient(cloudSocket, engine, () => {
+      // Signed out, or not verified yet: nothing to announce.
+      if (!apiClient.isVerified()) return null;
+      const id = terminalRelayGrants.deviceId();
+      return id ? { id, kind, name, appVersion: VERSION } : null;
+    });
+    clientRef.current = client;
+    const stop = client.start();
+    const unsubscribeUser = apiClient.subscribeCurrentUser(() => client.refresh());
+    return () => {
+      clientRef.current = null;
+      unsubscribeUser();
+      stop();
+      engine.dispose();
+    };
+  }, [attached, dialog, handle, kind, name]);
+
+  useEffect(() => {
+    if (!appActive) return;
+    clientRef.current?.activity();
+    const timer = setInterval(() => clientRef.current?.activity(), ACTIVE_PING_MS);
+    return () => clearInterval(timer);
+  }, [appActive, attached, kind]);
+
+  return null;
+}

package/src/plugins/builtin/cloud/terminal-relay/indicator.tsx

@@ -0,0 +1,82 @@
+import { useEffect, useState, useSyncExternalStore } from "react";
+import { Button } from "../../../../components/ui/button";
+import { Box } from "../../../../ui";
+import { t, tf } from "../../../../i18n";
+import { getSharedRegistry } from "../../../registry";
+import { requestAccountManagementTab } from "../../account-management/navigation";
+import type { RelayActivity } from "./engine";
+
+/** An assistant counts as connected for this long after its last call. */
+const CONNECTED_FOR_MS = 5 * 60_000;
+/** The chip brightens this long after each call. */
+const ACTING_FOR_MS = 2_500;
+
+interface ActivityState {
+  name: string;
+  clientId: string;
+  at: number;
+}
+
+let current: ActivityState | null = null;
+const listeners = new Set<() => void>();
+
+function emit(): void {
+  for (const listener of listeners) listener();
+}
+
+/** Fed by the relay engine. */
+export function recordRelayActivity(activity: RelayActivity): void {
+  if (activity.type === "acted") {
+    current = { name: activity.caller.name, clientId: activity.caller.id, at: activity.at };
+  } else if (current?.clientId === activity.clientId) {
+    current = null;
+  }
+  emit();
+}
+
+function subscribe(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/**
+ * A quiet chip in the status bar while a remote assistant drives this
+ * terminal: dim while connected, bright for a moment when it acts. It opens
+ * Account Management on the Agents tab, where the assistant can be revoked.
+ */
+export function TerminalRelayStatusWidget() {
+  const activity = useSyncExternalStore(subscribe, () => current, () => current);
+  const [now, setNow] = useState(() => Date.now());
+
+  useEffect(() => {
+    if (!activity) return;
+    setNow(Date.now());
+    const acting = setTimeout(() => setNow(Date.now()), ACTING_FOR_MS + 50);
+    const connected = setTimeout(() => setNow(Date.now()), CONNECTED_FOR_MS + 50);
+    return () => {
+      clearTimeout(acting);
+      clearTimeout(connected);
+    };
+  }, [activity]);
+
+  if (!activity || now - activity.at > CONNECTED_FOR_MS) return null;
+  const acting = now - activity.at < ACTING_FOR_MS;
+  return (
+    <Box paddingRight={1} flexShrink={0}>
+      <Button
+        label={acting ? tf("{name} is acting", { name: activity.name }) : tf("{name} connected", { name: activity.name })}
+        title={t("A remote assistant controls this terminal. Open Agents to revoke it.")}
+        variant="plain"
+        active={acting}
+        compact
+        stopPropagation
+        onPress={() => {
+          requestAccountManagementTab("agents");
+          getSharedRegistry()?.showPane("account-management");
+        }}
+      />
+    </Box>
+  );
+}

package/src/plugins/builtin/cloud/terminal-relay/manifest.ts

@@ -0,0 +1,234 @@
+import {
+  REMOTE_OPERATIONS,
+  REMOTE_RESOURCES,
+  remoteOperationToolName,
+} from "../../../../remote/schema";
+import type {
+  RemoteJsonSchema,
+  RemoteSideEffectLevel,
+  RemoteWriteTier,
+} from "../../../../remote/types";
+import {
+  operationPolicy,
+  patchPolicy,
+  policySentence,
+  readPolicy,
+  tierLabel,
+  type TerminalRelayPolicy,
+} from "./policy";
+
+/**
+ * The tools this app runs for a remote assistant, generated from the remote
+ * API schema: every operation is a tool, so a new operation reaches the
+ * assistant without anyone listing it. Gloom Cloud advertises these as
+ * `terminal.<name>` and adds its own `terminal.devices` and
+ * `terminal.call_result`.
+ */
+export const TERMINAL_RELAY_PROTOCOL = 1;
+
+export type TerminalRelayToolKind =
+  | { kind: "operation"; operation: string }
+  | { kind: "resource" }
+  | { kind: "patch" }
+  | { kind: "data" }
+  | { kind: "snapshot" }
+  | { kind: "pane-content" };
+
+export interface TerminalRelayToolDescriptor {
+  name: string;
+  title: string;
+  description: string;
+  inputSchema: RemoteJsonSchema;
+  tier: RemoteSideEffectLevel;
+  writeTier: RemoteWriteTier;
+  policy: TerminalRelayPolicy;
+  annotations: {
+    readOnly: boolean;
+    destructive: boolean;
+    idempotent: boolean;
+    openWorld: boolean;
+  };
+}
+
+interface TerminalRelayTool extends TerminalRelayToolDescriptor {
+  binding: TerminalRelayToolKind;
+}
+
+const DESTRUCTIVE_OPERATIONS = new Set(["layout.delete", "pane.close", "layout.closeFloating", "desktop.closeDetachedPane"]);
+const IDEMPOTENT_OPERATIONS = new Set([
+  "pane.show",
+  "pane.focus",
+  "ticker.select",
+  "ticker.switchTab",
+  "layout.switch",
+  "layout.focusRegion",
+  "layout.setGrid",
+  "app.closeCommandBar",
+]);
+
+function describe(text: string, tier: RemoteSideEffectLevel, policy: TerminalRelayPolicy): string {
+  return `${text} Tier: ${tierLabel(tier)}. ${policySentence(policy)}`;
+}
+
+function readTool(
+  name: string,
+  title: string,
+  text: string,
+  inputSchema: RemoteJsonSchema,
+  binding: TerminalRelayToolKind,
+): TerminalRelayTool {
+  const { policy } = readPolicy();
+  return {
+    name,
+    title,
+    description: describe(text, "none", policy),
+    inputSchema,
+    tier: "none",
+    writeTier: "read",
+    policy,
+    annotations: { readOnly: true, destructive: false, idempotent: true, openWorld: false },
+    binding,
+  };
+}
+
+const RESOURCE_LIST = REMOTE_RESOURCES.map(({ uri }) => uri).join(", ");
+
+function buildTools(): TerminalRelayTool[] {
+  const operations = REMOTE_OPERATIONS.map((operation): TerminalRelayTool => {
+    const { policy } = operationPolicy(operation.id);
+    const external = operation.sideEffectLevel === "external-side-effect"
+      || operation.sideEffectLevel === "external-trade"
+      || operation.sideEffectLevel === "network-write";
+    return {
+      name: remoteOperationToolName(operation.id),
+      title: operation.title,
+      description: describe(operation.description, operation.sideEffectLevel, policy),
+      inputSchema: operation.inputSchema,
+      tier: operation.sideEffectLevel,
+      writeTier: operation.writeTier,
+      policy,
+      annotations: {
+        readOnly: operation.sideEffectLevel === "none",
+        destructive: DESTRUCTIVE_OPERATIONS.has(operation.id) || operation.writeTier === "user-data" || external,
+        idempotent: IDEMPOTENT_OPERATIONS.has(operation.id),
+        openWorld: external,
+      },
+      binding: { kind: "operation", operation: operation.id },
+    };
+  });
+  return [
+    readTool(
+      "snapshot",
+      "Terminal: Snapshot",
+      "What is on screen: the active layout and the saved layouts, every pane with its placement, the focused pane and its ticker, the command bar and any open form.",
+      { type: "object", properties: {}, additionalProperties: false },
+      { kind: "snapshot" },
+    ),
+    readTool(
+      "pane_content",
+      "Terminal: Pane content",
+      "What one pane shows: its settings and runtime state, and the semantic UI nodes drawn in it (table rows, tabs, lists, buttons, chart data). paneId is an instance id from terminal.snapshot.",
+      {
+        type: "object",
+        properties: { paneId: { type: "string", minLength: 1 } },
+        required: ["paneId"],
+        additionalProperties: false,
+      },
+      { kind: "pane-content" },
+    ),
+    readTool(
+      "get_resource",
+      "Terminal: Get resource",
+      `Read one remote API resource. Resources: ${RESOURCE_LIST}. Configuration arrives with credentials removed.`,
+      {
+        type: "object",
+        properties: { resource: { type: "string", minLength: 1, description: "A resource URI, such as app://panes or app://pane-state/{paneId}." } },
+        required: ["resource"],
+        additionalProperties: false,
+      },
+      { kind: "resource" },
+    ),
+    readTool(
+      "market_data",
+      "Terminal: Market data",
+      "Market data through the terminal's own sources: search, quote, financials, secFilings, holders, analystResearch, corporateActions, earningsCalendar.",
+      {
+        type: "object",
+        properties: {
+          operation: {
+            type: "string",
+            enum: ["search", "quote", "financials", "secFilings", "holders", "analystResearch", "corporateActions", "earningsCalendar"],
+          },
+          query: { type: "string" },
+          symbol: { type: "string" },
+          exchange: { type: "string" },
+          count: { type: "integer", minimum: 1 },
+          symbols: { type: "array", items: { type: "string", minLength: 1 } },
+        },
+        required: ["operation"],
+        additionalProperties: false,
+      },
+      { kind: "data" },
+    ),
+    {
+      name: "patch_resource",
+      title: "Terminal: Patch resource",
+      description: `Apply a JSON Patch to a mutable resource: app://layout/current, app://pane-state/{paneId}, app://pane-settings/{paneId} or app://config. Pass expectRev from a read so a stale edit fails. Tier: local-write. ${policySentence(patchPolicy("app://layout/current").policy)} Patching app://config is confirmed by the person on each call.`,
+      inputSchema: {
+        type: "object",
+        properties: {
+          resource: { type: "string", minLength: 1 },
+          patch: {
+            type: "array",
+            minItems: 1,
+            items: {
+              type: "object",
+              properties: {
+                op: { type: "string", enum: ["add", "replace", "remove"] },
+                path: { type: "string" },
+                value: {},
+              },
+              required: ["op", "path"],
+              additionalProperties: false,
+            },
+          },
+          expectRev: { type: "string" },
+        },
+        required: ["resource", "patch"],
+        additionalProperties: false,
+      },
+      tier: "local-write",
+      writeTier: "ui-write",
+      policy: "allow",
+      annotations: { readOnly: false, destructive: true, idempotent: false, openWorld: false },
+      binding: { kind: "patch" },
+    },
+    ...operations,
+  ];
+}
+
+const TOOLS = buildTools();
+const TOOLS_BY_NAME = new Map(TOOLS.map((tool) => [tool.name, tool]));
+
+/** What the app announces to Gloom Cloud. */
+export function terminalRelayToolDescriptors(): TerminalRelayToolDescriptor[] {
+  return TOOLS.map(({ binding: _binding, ...descriptor }) => descriptor);
+}
+
+/** The app's own table: a name it did not generate is never run. */
+export function resolveTerminalRelayTool(name: string): TerminalRelayToolKind | null {
+  return TOOLS_BY_NAME.get(name)?.binding ?? null;
+}
+
+export function terminalRelayToolTitle(name: string): string {
+  return TOOLS_BY_NAME.get(name)?.title ?? name;
+}
+
+function resourcePatternMatches(pattern: string, value: string): boolean {
+  const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`^${escaped.replace(/\\\{[^}]+\\\}/g, "[^/]+")}$`).test(value);
+}
+
+export function isKnownRemoteResource(resource: string): boolean {
+  return REMOTE_RESOURCES.some(({ uri }) => resourcePatternMatches(uri, resource));
+}

package/src/plugins/builtin/cloud/terminal-relay/policy.ts

@@ -0,0 +1,153 @@
+import type { RemoteSideEffectLevel } from "../../../../remote/types";
+
+/**
+ * What a remote assistant connected through Gloom Cloud may do in this app.
+ *
+ * - `allow`: runs once the person approved the assistant for this terminal
+ *   (one prompt per assistant, see grants.ts).
+ * - `confirm`: the person confirms every single call in the app, after
+ *   reading what it will do. A remote assistant reads untrusted text and can
+ *   be steered by it, so anything that reaches an outside service (a broker
+ *   order, a transfer, a message, a plugin capability) asks each time.
+ * - `local-ui`: `allow` for semantic UI actions that only move, select or
+ *   type inside the app; `confirm` for every other action (press, submit,
+ *   activate), since a button can send an order or a message.
+ * - `navigation`: `allow` when the command-bar row opens a ticker or a pane;
+ *   `confirm` for rows that run a command.
+ *
+ * Every operation of the local remote API has a row, so the policy can be
+ * read in one place. An operation added to the schema without a row is
+ * still relayed, under `confirm`, never `allow`.
+ */
+export type TerminalRelayPolicy = "allow" | "confirm" | "local-ui" | "navigation";
+
+export interface TerminalRelayPolicyEntry {
+  policy: TerminalRelayPolicy;
+  /** Why, in one line, for reviewers. */
+  reason: string;
+}
+
+const ARRANGE = "Rearranges the person's own layout; layout.undo reverts it.";
+const OPEN = "Opens, focuses or navigates panes in this app only.";
+
+export const TERMINAL_RELAY_OPERATION_POLICY: Readonly<Record<string, TerminalRelayPolicyEntry>> = {
+  "app.openCommandBar": { policy: "allow", reason: "Opens the command bar; running a row is commandBar.activateResult." },
+  "app.closeCommandBar": { policy: "allow", reason: "Closes the command bar." },
+  "app.closeDialog": { policy: "allow", reason: "Closes the dialog on top as Esc would; a relay prompt answers Deny when closed." },
+  "app.setCommandBarQuery": { policy: "allow", reason: "Types into the command bar." },
+  "app.search": { policy: "allow", reason: "Opens command-bar search." },
+  "app.switchPanel": { policy: "allow", reason: OPEN },
+  "app.notify": { policy: "allow", reason: "Shows a local notification." },
+  "commandBar.activateResult": { policy: "navigation", reason: "A row can open a ticker or a pane, or run any command." },
+  "pane.show": { policy: "allow", reason: OPEN },
+  "pane.focus": { policy: "allow", reason: OPEN },
+  "pane.close": { policy: "allow", reason: "Closes a pane; layout.undo brings it back." },
+  "pane.createFromTemplate": { policy: "allow", reason: OPEN },
+  "view.create": { policy: "allow", reason: "Creates a custom view pane from data the app already reads." },
+  "view.update": { policy: "allow", reason: "Replaces a custom view's spec; layout.undo reverts it." },
+  "pane.setState": { policy: "allow", reason: "Patches a pane's runtime state." },
+  "pane.setSetting": { policy: "allow", reason: "Changes one pane setting." },
+  "ticker.navigate": { policy: "allow", reason: OPEN },
+  "ticker.pin": { policy: "allow", reason: OPEN },
+  "ticker.select": { policy: "allow", reason: OPEN },
+  "ticker.switchTab": { policy: "allow", reason: OPEN },
+  "layout.switch": { policy: "allow", reason: ARRANGE },
+  "layout.new": { policy: "allow", reason: "Adds a blank layout." },
+  "layout.rename": { policy: "allow", reason: "Renames a layout; renaming back restores it." },
+  "layout.duplicate": { policy: "allow", reason: "Copies a layout." },
+  "layout.delete": {
+    policy: "confirm",
+    reason: "Deleting a layout drops its undo history with it, so it cannot be reverted; asks each time.",
+  },
+  "layout.undo": { policy: "allow", reason: ARRANGE },
+  "layout.redo": { policy: "allow", reason: ARRANGE },
+  "layout.gridlock": { policy: "allow", reason: ARRANGE },
+  "layout.closeFloating": { policy: "allow", reason: ARRANGE },
+  "layout.placePane": { policy: "allow", reason: ARRANGE },
+  "layout.focusRegion": { policy: "allow", reason: OPEN },
+  "layout.setGrid": { policy: "allow", reason: ARRANGE },
+  "desktop.popOutPane": { policy: "allow", reason: "Moves a pane into its own desktop window." },
+  "desktop.dockPane": { policy: "allow", reason: "Docks a detached desktop pane back." },
+  "desktop.closeDetachedPane": { policy: "allow", reason: "Closes a detached desktop window." },
+  "desktop.focusDetachedPane": { policy: "allow", reason: "Focuses a detached desktop window." },
+  "capability.invoke": {
+    policy: "confirm",
+    reason: "Plugin capabilities reach outside services: broker orders, transfers, paid data, messages.",
+  },
+  "ui.invoke": { policy: "local-ui", reason: "A semantic action can scroll a list or press a Send or Submit button." },
+  "ui.invokeMatching": { policy: "local-ui", reason: "Same as ui.invoke, with the node picked by role and label." },
+};
+
+/** Reads never change anything; app://config arrives with credentials removed (redact.ts). */
+const TERMINAL_RELAY_READ_POLICY: TerminalRelayPolicyEntry = {
+  policy: "allow",
+  reason: "Reads what the app shows; credentials are removed from configuration.",
+};
+
+/** JSON Patch on a mutable resource. Configuration holds broker connections. */
+export function patchPolicy(resource: string): TerminalRelayPolicyEntry {
+  return resource === "app://config"
+    ? { policy: "confirm", reason: "Configuration holds broker connections and plugin settings." }
+    : { policy: "allow", reason: "Patches layout, pane state or pane settings; layout.undo reverts layout changes." };
+}
+
+/** Every read: snapshots, pane content, resources, market data. */
+export function readPolicy(): TerminalRelayPolicyEntry {
+  return TERMINAL_RELAY_READ_POLICY;
+}
+
+export function operationPolicy(operation: string): TerminalRelayPolicyEntry {
+  return TERMINAL_RELAY_OPERATION_POLICY[operation]
+    ?? { policy: "confirm", reason: "Not reviewed for remote control yet." };
+}
+
+/**
+ * UI actions that only scroll, move a cursor, select or type inside the app.
+ * Everything else a node exposes (press, submit, activate, toggle, release)
+ * may act outside it and asks each time.
+ */
+export const LOCAL_UI_ACTIONS: ReadonlySet<string> = new Set([
+  "scroll",
+  "scrollBy",
+  "scrollTo",
+  "moveCursor",
+  "drag",
+  "selectRow",
+  "sort",
+  "select",
+  "setValue",
+  "focus",
+  "blur",
+  "hover",
+  "open",
+  "close",
+]);
+
+/** Command-bar rows that only open a ticker or a pane. */
+export const NAVIGATION_RESULT_KINDS: ReadonlySet<string> = new Set([
+  "ticker",
+  "ticker-search",
+  "pane",
+  "pane-template",
+  "route",
+  "search",
+  "mode",
+]);
+
+/** What the policy carries into a tool's description. */
+export function policySentence(policy: TerminalRelayPolicy): string {
+  switch (policy) {
+    case "allow":
+      return "Runs once the person approved this assistant in Gloom.";
+    case "confirm":
+      return "The person confirms each call in Gloom; unanswered after 60 s it is denied.";
+    case "local-ui":
+      return "Scroll, select, setValue and focus run once the assistant is approved; press, submit and other actions are confirmed by the person on each call.";
+    case "navigation":
+      return "Rows that open a ticker or a pane run once the assistant is approved; rows that run a command are confirmed by the person on each call.";
+  }
+}
+
+export function tierLabel(level: RemoteSideEffectLevel): string {
+  return level === "none" ? "read" : level;
+}