privateer-agent 0.12.30 → 0.12.32

package/src/computer/space.ts

@@ -0,0 +1,289 @@
+/**
+ * The coordinate space — the one thing in GUI control that has to be exactly right.
+ *
+ * WHY THIS IS ITS OWN MODULE, AND PURE. Three different pixel grids are in play at
+ * once and nothing in the system tells you when you have mixed them up:
+ *
+ *   • DEVICE pixels — what the display actually has. A 16" Retina panel is 3456×2234.
+ *   • POINTS — what macOS's input APIs take (CGEvent), half that on a 2× display.
+ *   • AGENT space — the grid of the downscaled PNG the model is actually looking at.
+ *     A 3456px-wide frame is ~5 MB of base64 and more pixels than any vision model
+ *     resolves; every implementation downscales, so the model's coordinates are in a
+ *     space that exists nowhere in the OS.
+ *
+ * The failure mode is not a crash. If capture scales and input does not, every click
+ * lands at roughly half or twice the intended place, the model sees a screenshot where
+ * nothing happened, and it tries again slightly differently — burning tokens and money
+ * while quietly clicking on whatever else is there. That is the single most expensive
+ * bug this feature can have, so the rule is:
+ *
+ *   EVERY coordinate crossing the tool boundary is in AGENT space, and the ONLY
+ *   conversion to device pixels happens here.
+ *
+ * The helper is told the target size up front and does the downscale natively (a
+ * CoreGraphics resize is far cheaper than shipping a full-resolution PNG down a pipe
+ * and resampling it in JS), so the image the model receives IS agent space by
+ * construction rather than by a second calculation that could disagree with this one.
+ *
+ * TWO factors, not one. Rounding the target size means `regionWidth / factor` is not
+ * generally an integer, so a single factor leaves a fractional error that grows toward
+ * the far edge of the screen — precisely where a click is most likely to miss (a menu
+ * bar item, a window's close button). Deriving the factor per-axis FROM the rounded
+ * size instead makes the mapping exact at both edges.
+ *
+ * PIXEL CENTRES, not corners. `a * factor` biases every click toward the top-left of
+ * the cell it names and can land exactly on a boundary; `(a + 0.5) * factor` lands in
+ * the middle of the agent pixel the model pointed at.
+ *
+ * ONE DISPLAY AT A TIME. Every coordinate here is local to a single display, because a
+ * global device-pixel space does not exist on a mixed-DPI desktop — see Display.originX
+ * for the collision that makes. Turning a display-local device pixel into something the
+ * OS will accept is the platform helper's job, and only its job.
+ *
+ * Pure — no I/O, no platform calls — so tests/computer.test.ts can pin the round trip
+ * over the display shapes that actually ship (1×, 2×, ultrawide, a small panel) rather
+ * than only the one on the developer's desk.
+ */
+
+/** A display as the platform helper reports it. All lengths in DEVICE pixels. */
+export interface Display {
+  /** Stable within a session; what the tools' `display` parameter names. */
+  id: string;
+  /** Human label for the approval prompt — "Built-in Retina Display". */
+  label: string;
+  width: number;
+  height: number;
+  /** Device pixels per point. 2 on Retina, 1 on a plain panel, 1.5 on some Windows. */
+  scale: number;
+  /**
+   * Where this display sits in the global desktop, in POINTS — the space the operating
+   * system lays displays out in, and the space its input APIs take. A display placed to
+   * the LEFT of the primary has a negative originX.
+   *
+   * INFORMATIONAL ONLY: nothing in this module converts through it, and the tools never
+   * send it anywhere. It is here so a capability listing can say where a screen is.
+   *
+   * WHY NOT DEVICE PIXELS, which is what an earlier version of this file used. There is
+   * no coherent global device-pixel space on a mixed-DPI desktop. Multiply each
+   * display's point origin by its OWN scale and the ranges collide: a 2x laptop
+   * (3456px / 1728pt wide) at origin 0 owns device px 0-3455, while a 1x monitor placed
+   * beside it at point origin 1728 would claim 1728-4287 — so half of one screen's
+   * coordinates also name the other's, and a click meant for the second monitor lands
+   * on the first. Every coordinate below is therefore LOCAL to one display, and the
+   * platform helper — which knows that display's bounds and scale — is the only thing
+   * that converts into the OS's global space.
+   */
+  originX: number;
+  originY: number;
+  primary: boolean;
+}
+
+/**
+ * The mapping between one captured frame and the display it came from. Built by
+ * planCapture, handed to the helper as the capture request, and kept for as long as
+ * the model might send coordinates back against that frame.
+ */
+export interface CapturePlan {
+  displayId: string;
+  /** Agent space: the exact pixel size of the image the model is shown. */
+  width: number;
+  height: number;
+  /** Agent px → device px, per axis. Derived from the rounded size; see the header. */
+  factorX: number;
+  factorY: number;
+  /** The captured region's size in device px (today: the whole display). */
+  regionWidth: number;
+  regionHeight: number;
+}
+
+/** A point in agent space — the grid of the frame the model was shown. */
+export interface AgentPoint {
+  x: number;
+  y: number;
+}
+
+/**
+ * A point in ONE display's own device pixels, origin at that display's top-left. What
+ * the helper is given, alongside the display id — see Display.originX for why this is
+ * never a global coordinate.
+ */
+export interface DevicePoint {
+  x: number;
+  y: number;
+}
+
+/**
+ * The longest edge, in agent pixels, a captured frame is reduced to.
+ *
+ * 1400 is chosen against what the models can actually resolve rather than what looks
+ * nice: Claude tiles vision input at roughly 1.15k on the long edge and gains nothing
+ * above ~1568, and a 1400px frame of a 2× display is a 2:1 reduction — enough that
+ * menu-bar text is still legible when the model needs to read it. Raising this costs
+ * tokens on every single screenshot in a loop that takes many; lowering it makes small
+ * UI unreadable and the model start guessing.
+ */
+export const DEFAULT_MAX_EDGE = 1400;
+
+/** Bounds on what a caller may ask for, so one tool call can't blow up a turn's budget. */
+export const MIN_MAX_EDGE = 320;
+export const MAX_MAX_EDGE = 2400;
+
+export function clampMaxEdge(requested: number | undefined): number {
+  if (!Number.isFinite(requested as number)) return DEFAULT_MAX_EDGE;
+  return Math.min(MAX_MAX_EDGE, Math.max(MIN_MAX_EDGE, Math.round(requested as number)));
+}
+
+/**
+ * Work out the agent space for capturing `display` whole.
+ *
+ * Never upscales: a small display stays at its native size (factor 1) rather than being
+ * blown up to the max edge, which would cost tokens for pixels that carry no detail.
+ */
+export function planCapture(display: Display, maxEdge: number = DEFAULT_MAX_EDGE): CapturePlan {
+  const edge = clampMaxEdge(maxEdge);
+  const longest = Math.max(display.width, display.height);
+  const reduction = longest > edge ? longest / edge : 1;
+
+  // At least 1px each way — a degenerate display report must not produce a zero-sized
+  // plan whose factors are Infinity.
+  const width = Math.max(1, Math.round(display.width / reduction));
+  const height = Math.max(1, Math.round(display.height / reduction));
+
+  return {
+    displayId: display.id,
+    width,
+    height,
+    factorX: display.width / width,
+    factorY: display.height / height,
+    regionWidth: display.width,
+    regionHeight: display.height,
+  };
+}
+
+/**
+ * The longest edge of the small copy sent with a permission prompt.
+ *
+ * Deliberately far below DEFAULT_MAX_EDGE. The model needs to read menu text; a human
+ * approving a click needs to recognise the window and see where the marker is, which
+ * 480px does at a glance. It also has to cross a relay to a phone for every single
+ * action — the full frame is ~1 MB of base64 and this is nearer 40 KB, and an approval
+ * that takes a second to arrive is one people stop reading.
+ */
+export const PREVIEW_MAX_EDGE = 480;
+
+/** The preview's pixel size for a given plan, preserving its aspect. */
+export function planPreview(plan: CapturePlan, maxEdge: number = PREVIEW_MAX_EDGE): { width: number; height: number } {
+  const longest = Math.max(plan.width, plan.height);
+  const reduction = longest > maxEdge ? longest / maxEdge : 1;
+  return {
+    width: Math.max(1, Math.round(plan.width / reduction)),
+    height: Math.max(1, Math.round(plan.height / reduction)),
+  };
+}
+
+/** Is this point inside the frame the model was actually shown? */
+export function isInFrame(pt: AgentPoint, plan: CapturePlan): boolean {
+  return (
+    Number.isFinite(pt.x) &&
+    Number.isFinite(pt.y) &&
+    pt.x >= 0 &&
+    pt.y >= 0 &&
+    pt.x < plan.width &&
+    pt.y < plan.height
+  );
+}
+
+/**
+ * Math.round produces -0 for any input in [-0.5, 0), which is what the top-left corner
+ * of a frame maps back to. It compares equal to 0 with `==` and survives JSON, so it
+ * would never have shown up in behaviour — but it is not 0 under Object.is or a strict
+ * deep-equal, so it turns any future test or cache key over a coordinate into a
+ * mismatch that reads as a real bug. Normalized once, here.
+ */
+function norm(v: number): number {
+  return v + 0;
+}
+
+/**
+ * One agent pixel's device coordinate: the device pixel nearest the middle of the cell
+ * that agent pixel covers, CONSTRAINED to that cell.
+ *
+ * The constraint is the whole point, and two simpler versions both fail:
+ *
+ *   • round(origin + (a + 0.5) * factor) overshoots at the far edge. A 1024-wide
+ *     display at factor 1 sends its rightmost pixel (1023) to round(1023.5) = 1024 —
+ *     the first pixel of the NEXT display. A click on a window's close button or a
+ *     right-edge scrollbar lands on the monitor beside it.
+ *   • floor(...) fixes that and breaks the round trip, because flooring the centre can
+ *     leave the cell it came from: at factor 1.44036, agent row 1549 covers device
+ *     [2231.12, 2232.56), its centre is 2231.84, and floor gives 2231 — which is row
+ *     1548. Off by one, over most of the screen rather than at its edge.
+ *
+ * Deriving the cell's integer bounds and clamping into them is exact for both. Since
+ * planCapture never upscales, factor >= 1 and every cell contains at least one integer,
+ * so the clamp always has something to land on.
+ */
+function cellDevice(index: number, factor: number): number {
+  const lo = Math.ceil(index * factor);
+  const hi = Math.ceil((index + 1) * factor) - 1;
+  const centre = Math.round((index + 0.5) * factor);
+  if (hi < lo) return lo; // a sub-pixel cell — impossible today, but not worth a NaN
+  return Math.min(hi, Math.max(lo, centre));
+}
+
+/**
+ * Agent space → the global desktop, in device pixels.
+ *
+ * THROWS on a point outside the frame rather than clamping to the edge. An edge-clamped
+ * click is a plausible-looking place that is not where the model aimed, and the model
+ * would read the resulting screenshot as "the click did something unexpected" instead
+ * of "my coordinates were wrong". An out-of-frame point is always a mistake, and saying
+ * so is what stops the retry loop this whole module exists to prevent.
+ */
+export function agentToDevice(pt: AgentPoint, plan: CapturePlan): DevicePoint {
+  if (!isInFrame(pt, plan)) {
+    throw new RangeError(
+      `(${pt.x}, ${pt.y}) is outside the captured frame, which is ${plan.width}×${plan.height}. ` +
+        `Coordinates must come from the most recent screen_capture of this display.`,
+    );
+  }
+  return {
+    x: norm(cellDevice(pt.x, plan.factorX)),
+    y: norm(cellDevice(pt.y, plan.factorY)),
+  };
+}
+
+/**
+ * The inverse — which agent pixel's cell contains this device point. Used to report the
+ * pointer's current position back in the space the model is thinking in.
+ *
+ * `floor` of the offset, not a rounded centre: the cell for index a is
+ * [origin + a*factor, origin + (a+1)*factor), so this is the exact inverse of
+ * cellDevice above rather than an approximation that agrees with it most of the time.
+ */
+export function deviceToAgent(pt: DevicePoint, plan: CapturePlan): AgentPoint {
+  return {
+    x: norm(Math.floor(pt.x / plan.factorX)),
+    y: norm(Math.floor(pt.y / plan.factorY)),
+  };
+}
+
+/** Pick the display a tool call means: the one named, else the primary, else the first. */
+export function resolveDisplay(displays: Display[], id: string | undefined): Display | undefined {
+  if (!displays.length) return undefined;
+  if (id) return displays.find((d) => d.id === id);
+  return displays.find((d) => d.primary) ?? displays[0];
+}
+
+/** One line per display for computer_capabilities — sizes in the space the model uses. */
+export function describeDisplays(displays: Display[], maxEdge: number = DEFAULT_MAX_EDGE): string[] {
+  return displays.map((d) => {
+    const plan = planCapture(d, maxEdge);
+    const scale = d.scale !== 1 ? ` @${d.scale}×` : "";
+    const primary = d.primary ? " (primary)" : "";
+    return (
+      `  ${d.id}: ${d.label}${primary} — ${d.width}×${d.height} device px${scale}; ` +
+      `you will see it as ${plan.width}×${plan.height} and give coordinates in that space`
+    );
+  });
+}

package/src/config/computerControl.ts

@@ -0,0 +1,67 @@
+/**
+ * May this process drive the machine's screen, mouse and keyboard at all?
+ *
+ * THE DEFAULT IS OFF, and that is the one way this differs from every other switch in
+ * config/. relayExposure.ts defaults to ALLOWED because an unset variable there means
+ * "nobody has expressed a preference, and the surfaces that open a socket are already
+ * explicit acts". The opposite is true here: GUI control is not an extension of what
+ * the agent could already do, it is a way around the whole moat. The permission gate
+ * confines file operations to the working directory, refuses protected paths and
+ * pattern-matches dangerous shell — and a mouse can open Terminal and type any of it,
+ * click Allow on another application's consent dialog, or drive a browser that is
+ * already logged into the user's bank. Nothing in classify.ts can see any of that
+ * happen. So it exists only where a human has said, in as many words, that it may.
+ *
+ * ARMING IS A SEPARATE ACT FROM APPROVING. The gate still asks before every action
+ * (permissions/mode.ts — kind "computer" never auto-allows, not even under `bypass`).
+ * This switch decides something prior: whether the tools are REGISTERED at all. An
+ * unarmed session does not have a `computer_control` that gets denied, it has no such
+ * tool — the same distinction buildMoat already draws for web ("web off should mean the
+ * tool doesn't exist for that run, not that it exists and is denied"). A model with a
+ * tool it is refused on every call spends its context rediscovering that; a model
+ * without the tool says it cannot do that and moves on.
+ *
+ * WHAT THIS DOES NOT DEFEND AGAINST, stated plainly because the alternative is implying
+ * a guarantee we don't have: `--no-quarter` (PRIVATEER_NO_QUARTER) and the app's
+ * unattended toggle are still a total bypass of the gate, computer actions included.
+ * That is deliberate — a second, subtly-different total-bypass lever is worse than one
+ * everybody understands — but it means ARMING plus NO-QUARTER is a session that will
+ * move the mouse without asking. Both are explicit human acts, and the app's copy has
+ * to say so where the two can be turned on together.
+ *
+ * Read at CALL time rather than latched at boot, for the reason relayExposure.ts gives:
+ * a long-lived process whose parent re-stamps its environment (the desktop shell
+ * re-spawning a child with a different answer) must honour the new answer on its next
+ * tick rather than the one it happened to start with.
+ */
+
+const ON = new Set(["1", "true", "on", "yes"]);
+
+/** The environment variable the desktop shell and the CLI flag both write. */
+export const COMPUTER_CONTROL_ENV = "PRIVATEER_COMPUTER_CONTROL";
+
+/**
+ * Whether GUI control tools may be registered for this process.
+ *
+ * Unset, empty, or anything not in ON ⇒ false. Deliberately an allow-list rather than
+ * a deny-list: a typo ("PRIVATEER_COMPUTER_CONTROL=ture") must fail CLOSED. The
+ * inverse spelling would arm the machine on a misspelling, which is the wrong direction
+ * for the one capability that can click through another app's consent dialog.
+ */
+export function computerControlArmed(): boolean {
+  const v = process.env[COMPUTER_CONTROL_ENV]?.trim().toLowerCase();
+  return v ? ON.has(v) : false;
+}
+
+/**
+ * What to tell a user who asked for something the tools would have done. Written for
+ * the model to relay verbatim, so it names the switch rather than the variable: someone
+ * reading it is in an app or a terminal, not editing an environment.
+ */
+export function computerControlDisarmedHint(): string {
+  return (
+    "Screen control is off for this machine. It is off by default because it lets an agent " +
+    "click and type anywhere, outside every other limit in place. Turn it on in Privateer → " +
+    "Settings → Screen control, or start the CLI with --allow-computer-control."
+  );
+}

package/src/config/moat.ts

@@ -140,6 +140,21 @@ interface MoatCaps {
   web: false | "account" | "guarded";
   media: boolean;
   mcp: boolean;
+  /**
+   * GUI control — screenshots, mouse and keyboard (src/tools/computer.ts). A CEILING
+   * like web and media, and ANDed with computerControlArmed(), which is OFF unless a
+   * human has said otherwise.
+   *
+   * FALSE FOR EVERY UNATTENDED KIND, and this is the row least safe to flip. The four
+   * headless kinds run with nobody watching, and permissions/mode.ts answers "ask" for
+   * every computer action — so a harbor routine granted these tools would not run
+   * unattended, it would WEDGE on a relayed prompt nobody is there to answer. That is
+   * the benign reading. The other one is that a scheduled run is the least supervised
+   * thing we ship and prompt injection reaches it through its own inputs, which is not
+   * a combination to give a mouse to. Attended kinds only: the desktop window and the
+   * dev REPL, both with a human at the keyboard who can see what moved.
+   */
+  computer: boolean;
   /** PRIVATEER.md project context + /init (extensions/privateer-context.ts). */
   context?: boolean;
   /** The folder's own skills, contributed from ~/.privateer rather than the user's tree. */
@@ -157,12 +172,12 @@ interface MoatCaps {
 }
 
 const CAPABILITIES: Record<MoatKind, MoatCaps> = {
-  "harbor-session": { web: "account", media: true, mcp: true },
-  "live-task": { web: false, media: true, mcp: false },
-  channels: { web: "account", media: true, mcp: false },
-  acp: { web: "account", media: true, mcp: false },
-  repl: { web: false, media: true, mcp: false },
-  desktop: { web: "guarded", media: true, mcp: true, context: true, spawnSkills: true, privacyRepairs: true },
+  "harbor-session": { web: "account", media: true, mcp: true, computer: false },
+  "live-task": { web: false, media: true, mcp: false, computer: false },
+  channels: { web: "account", media: true, mcp: false, computer: false },
+  acp: { web: "account", media: true, mcp: false, computer: false },
+  repl: { web: false, media: true, mcp: false, computer: true },
+  desktop: { web: "guarded", media: true, mcp: true, computer: true, context: true, spawnSkills: true, privacyRepairs: true },
 };
 
 /**
@@ -308,6 +323,31 @@ export async function buildMoat(opts: MoatOptions): Promise<ExtensionFactory[]>
   const { makeComposeTools } = await import("../tools/videoCompose.ts");
   factories.push(makeComposeTools());
 
+  // GUI control. TWO conditions, and they answer different questions: `caps.computer`
+  // is whether this KIND of session may ever have it, `computerControlArmed()` is
+  // whether this MACHINE's owner has turned it on. Omitted as a factory rather than
+  // registered-and-denied for the reason the web block above gives — a tool that
+  // refuses every call teaches the model to keep trying, where an absent one makes it
+  // say it cannot do that and move on. Read here, at build time, and the desktop
+  // rebuilds its session when the switch changes (agentSession's setModel path), so a
+  // user who arms it does not have to restart to be believed.
+  if (caps.computer) {
+    const { computerControlArmed } = await import("./computerControl.ts");
+    if (computerControlArmed()) {
+      const { makeComputerTools } = await import("../tools/computer.ts");
+      const { ComputerPreviewSink } = await import("../computer/preview.ts");
+      // ONE sink, created here and handed to both halves: the tools write each capture
+      // into it, and the gate reads a preview out when it asks about a click. This is
+      // the only place that pairing can be made, because it is the only place that
+      // holds both the gate and the tool factory — and it has to be per session (the
+      // desktop runs one per window in one process), which is exactly what this
+      // function already is. See computer/preview.ts for what module state would cost.
+      const preview = new ComputerPreviewSink();
+      opts.gate.computerPreview = preview;
+      factories.push(makeComputerTools(preview));
+    }
+  }
+
   if (caps.mcp) {
     // Registers the tools from the shared agent/mcp.json — the same projection the app's
     // MCP manager writes over the relay. No servers configured → a no-op. The specifier is

package/src/config/moatManifest.json

@@ -17,6 +17,7 @@
     { "entry": "extensions/privateer-privacy.ts", "name": "privateer-privacy", "note": "pi-privacy + account tier resolver" },
     { "entry": "extensions/privateer-connect.ts", "name": "privateer-connect", "note": "/connect — MCP connector manager" },
     { "entry": "extensions/privateer-media.ts", "name": "privateer-media", "note": "image/video/speech/music + ffmpeg compose" },
+    { "entry": "extensions/privateer-computer.ts", "name": "privateer-computer", "note": "screen control — screenshots, mouse and keyboard (off unless armed with --allow-computer-control)" },
     { "entry": "extensions/privateer-desktop.ts", "name": "privateer-desktop", "note": "/desktop — open the Privateer desktop app" },
     { "entry": "extensions/privateer-hints.ts", "name": "privateer-hints", "note": "rotating tips in the working line + /hints" },
     { "entry": "extensions/privateer-update.ts", "name": "privateer-update", "note": "tool pack updates in place — banner flag + /update" },

package/src/config/privacyPolicy.ts

@@ -35,6 +35,7 @@ import { addPiiAllow, piiAllowEntries, removePiiAllow } from "./piiAllow.ts";
 import { cliPalette, detectScheme } from "../ui/palette.ts";
 import { accountPosture, privateerChannel } from "../providers/account.ts";
 import { hasCredentials } from "../auth/privateer.ts";
+import { writePiDefaultModel } from "../providers/defaultModel.ts";
 
 // Color-coat pi-privacy's auto-redact notice as the moat acting on your behalf: the red
 // no-quarter flag (same glyph and color as the no-quarter banner in chat.ts and the gate
@@ -168,7 +169,45 @@ function registerPrivacyCommand(pi: any): void {
 export function privacyExtension() {
   const privacy = makePiPrivacyExtension(sharedPrivacyOptions());
   return function privateerPrivacyCore(pi: any): void {
-    privacy(pi);
+    privacy(persistingModelPicks(pi));
     registerPrivacyCommand(pi);
   };
 }
+
+/**
+ * pi-privacy's `/models` picker switched the live session and stopped there, so the
+ * pick lasted exactly as long as the terminal and the next one launched on whatever
+ * settings.json still said. Pi persists a switch only for a caller that passes
+ * `{ persist: true }`, and the extension api it reaches setModel through forwards no
+ * options at all (see savedPiDefaultSpec in providers/defaultModel.ts).
+ *
+ * Pi's own selector splits the two — Enter switches for the session, ctrl+s makes it
+ * the default. OUR picker has no second key to press and never advertised a
+ * distinction, so a pick made in it means "this is my model": we persist it.
+ *
+ * Wrapped here rather than fixed inside pi-privacy so the rule sits with the rest of
+ * what Privateer configures on that extension, and so it stays scoped to the picker.
+ * The brand extension's sign-in switch shares the same api and deliberately does NOT
+ * get this — writePiDefaultModel says why an automatic switch must not persist.
+ *
+ * A Proxy, not a spread: the api object is a plain literal today, but a spread of a
+ * class instance would silently drop every method and take pi-privacy down with it.
+ * Forwarding leaves that failure mode impossible.
+ */
+function persistingModelPicks(pi: any): any {
+  if (typeof pi?.setModel !== "function") return pi;
+  const setModel = async (model: any) => {
+    const ok = await pi.setModel(model);
+    // false = the host has no key for that provider, so nothing switched and there is
+    // nothing to remember. Anything else (true, undefined) is a switch that happened.
+    if (ok !== false && model?.provider && model?.id) writePiDefaultModel(`${model.provider}/${model.id}`);
+    return ok;
+  };
+  return new Proxy(pi, {
+    get(target, prop, receiver) {
+      if (prop === "setModel") return setModel;
+      const value = Reflect.get(target, prop, receiver);
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  });
+}

package/src/config/relayExposure.ts

@@ -0,0 +1,26 @@
+// Whether this process may open a cloud relay socket at all.
+//
+// Distinct from "is remote access on" — that is a decision each surface already
+// makes for itself (`/remote-access` in the TUI, a running harbor's syncRelay).
+// This is the machine's answer to a prior question: MAY that decision be yes?
+//
+// Unset means ALLOWED, and that default is what keeps every existing surface
+// unchanged: a `privateer harbor` someone started by hand is a harbor they asked
+// to be reachable, and the CLI's /remote-access has always been an explicit act.
+// Nothing in this repo sets the variable.
+//
+// The desktop shell is the caller that does. There, remote access is a per-machine
+// preference that defaults OFF (a GUI app that auto-starts a harbor would otherwise
+// put a socket on the relay for a user who never asked for one), so the shell stamps
+// its answer into the harbor child's environment.
+//
+// Read at CALL time rather than latched at boot, so a harbor that was already
+// running when the shell re-spawned it with a different answer honours the new one
+// on its next tick instead of the value it happened to start with.
+const OFF = new Set(["0", "false", "off", "no"]);
+
+export function relayExposureAllowed(): boolean {
+  const v = process.env.PRIVATEER_RELAY_EXPOSURE?.trim().toLowerCase();
+  if (!v) return true;
+  return !OFF.has(v);
+}

package/src/ext/permissionGate.ts

@@ -75,6 +75,17 @@ export interface GateController {
   redact?(text: string): string;
   // Hard ceiling on waiting for a decision before failing closed.
   approvalTimeoutMs?: number;
+  /**
+   * This session's screen-control preview sink (computer/preview.ts), when the session
+   * has screen control at all. Set by buildMoat, which creates the one object the
+   * computer tools write frames into and this reads them out of.
+   *
+   * It exists because a GUI approval is the one prompt that cannot be evaluated from
+   * words — see ApprovalPreview in permissions/gate.ts. Absent ⇒ computer approvals
+   * carry no picture and fall back to the text-only prompt, which is what every non-GUI
+   * kind has always been.
+   */
+  computerPreview?: { previewFor(toolName: string, input: unknown): import("../permissions/gate.ts").ApprovalPreview | undefined };
 }
 
 export interface GateBlock {
@@ -127,6 +138,20 @@ export async function decideToolCall(
   });
   if (!req) return undefined; // no gate needed — read-only/in-scope/meta
 
+  // Attach the picture a GUI action is actually about. Done HERE rather than in
+  // classifyToolCall because the classifier is pure over {toolName, input} and has no
+  // route to a screenshot — see computer/preview.ts. Guarded on the kind so nothing
+  // else ever carries an image, and wrapped because a preview is a nicety: failing to
+  // build one must never fail the approval it was meant to illustrate.
+  if (req.kind === "computer" && ctrl.computerPreview) {
+    try {
+      const preview = ctrl.computerPreview.previewFor(toolName, input);
+      if (preview) req.preview = preview;
+    } catch {
+      /* no picture; the text-only prompt still stands */
+    }
+  }
+
   // Route the ask: a remote-driven turn goes to the relay approver (if wired),
   // otherwise the local UI. ModeGate decides *whether* to ask; this decides *who*.
   const ask = (r: PermissionRequest): Promise<AskOutcome> =>

package/src/harbor/index.ts

@@ -65,6 +65,7 @@ import { redactText, collectSecrets } from "../util/redact.ts";
 import { startIpcServer, sendToHarbor, describeRelay, formatDuration, HarborAlreadyRunningError, type IpcRequest, type IpcResponse, type RelayStatus } from "./ipc.ts";
 import { serializeBuild } from "./buildLock.ts";
 import { isHosted, publishRelayPub, webEnabled, mediaEnabled } from "../config/hosted.ts";
+import { relayExposureAllowed } from "../config/relayExposure.ts";
 import { WEB_TOOL_NAMES } from "../tools/web.ts";
 import { MEDIA_TOOL_NAMES } from "../tools/media.ts";
 import { COMPOSE_TOOL_NAMES } from "../tools/videoCompose.ts";
@@ -360,6 +361,13 @@ export class Harbor {
     // `relay` delivery — so the "Privateer Local Harbor" terminal is always reachable
     // from the app for management (including creating the very first routine).
     if (!hasCredentials()) return;
+    // …unless this machine says remote access is off. Checked HERE, beside the
+    // credential, because both are conditions on being reachable rather than on
+    // being useful: a harbor refused a socket still fires every routine on its
+    // schedule and still delivers results to the account outbox. Only the app's
+    // live management view goes away. Re-read each tick (see relayExposure.ts), so
+    // a shell that re-spawns us with a different answer is obeyed on the next one.
+    if (!relayExposureAllowed()) return;
     this.relay = new RelayClient(
       {
         onPrompt: () => {},
@@ -1286,6 +1294,18 @@ export class Harbor {
       // permanent state: tick() re-runs syncRelay(), so a harbor that came up signed
       // out connects on its own once you sign in. Reported as "connecting" because
       // that is what it now is.
+      //
+      // The machine switch is reported BEFORE the credential, and that order is the
+      // honest one: a machine with remote access off is not waiting on a login, and
+      // telling someone to sign in to fix a setting sends them to the wrong screen.
+      if (!relayExposureAllowed()) {
+        return {
+          termId,
+          connected: false,
+          reason: "disabled",
+          detail: "remote access is off for this computer — turn it on in the Privateer app",
+        };
+      }
       const signedIn = hasCredentials();
       return {
         termId,

package/src/harbor/ipc.ts

@@ -53,9 +53,12 @@ export type IpcRequest =
  *   terminated  remote access was switched off from the app; needs a restart
  *   signed-out  no account credentials on this machine
  *   refused     the server said no (plan's agent cap, rejected ticket) — standing
+ *   disabled    remote access is off for this MACHINE (PRIVATEER_RELAY_EXPOSURE) —
+ *               standing, and the one reason here that is a setting rather than a
+ *               fault, so the app words it as an invitation rather than an error
  *   connecting  genuinely still trying; this one really is worth a moment
  */
-export type RelayReason = "terminated" | "signed-out" | "refused" | "connecting";
+export type RelayReason = "terminated" | "signed-out" | "refused" | "disabled" | "connecting";
 
 /**
  * The harbor's view of its own relay connection, reported by `status`.