privateer-agent 0.12.14 → 0.12.15

package/README.md

@@ -396,6 +396,12 @@ Download for [macOS](https://privateer.pro/download/mac) (Apple silicon),
 [macOS Intel](https://privateer.pro/download/mac-intel), or
 [Windows](https://privateer.pro/download/windows).
 
+Once it's installed, **`/desktop`** in the terminal brings it up — no Spotlight detour. It
+opens the app, not a copy of this conversation: the desktop hosts its own session, so pick
+the folder you were working in from **File ▸ Spawn Privateer at…** and it starts on the same
+model and connectors this terminal uses (the per-folder defaults live in `~/.privateer`,
+which both read).
+
 It's an early release and **not yet code-signed or notarized** — macOS will warn on first
 open. Routines and channels deliberately aren't hosted here: those belong to the always-on
 harbor, so background work still wants `privateer harbor install`.
@@ -640,6 +646,7 @@ drop your own into `~/.privateer/agent/extensions/` and it loads the same way, g
 | `/extensions` | list loaded Pi extensions |
 | `/web-tools` | point `web_search`/`web_fetch` at a search provider of your own (signed in, they already work on your account) |
 | `/init` | scaffold a starter `PRIVATEER.md` in this directory |
+| `/desktop` | open the [desktop app](#desktop-app) — same login, same per-folder defaults |
 | `/update` · `/privateer` | update to the latest release / Privateer status and posture |
 
 Shell subcommands: `privateer` (interactive), `privateer update`, `privateer harbor …`,

package/extensions/privateer-desktop.ts

@@ -0,0 +1,54 @@
+// /desktop — bring up the Privateer desktop app from the terminal.
+//
+// The two front ends already share everything that matters: one ~/.privateer home,
+// so one login, one model config, one MCP catalog, one set of per-folder spawn
+// defaults. What was missing was a way across. Getting from a terminal to the app
+// meant leaving the terminal — Spotlight, the Dock, a Start-menu hunt — which is
+// exactly the kind of small friction that leaves a shipped app unopened.
+//
+// What it does NOT do is carry the conversation over: the desktop hosts its own
+// in-process session and takes no folder argument (see src/config/desktopApp.ts),
+// so this opens the app and says how to point a window at the folder you were just
+// working in. When the app isn't installed we say so once, with the download page
+// for this platform, and never again unasked — the working-line tip in
+// privateer-hints.ts only fires on a machine that HAS it.
+
+import {
+  desktopAppPath,
+  desktopDownloadAltUrl,
+  desktopDownloadUrl,
+  openDesktopApp,
+} from "../src/config/desktopApp.ts";
+
+export default function privateerDesktop(pi: any): void {
+  pi.registerCommand?.("desktop", {
+    description: "Open the Privateer desktop app — same login, same per-folder defaults",
+    handler: (_args: string, ctx: any) => {
+      const app = desktopAppPath();
+
+      if (app) {
+        const cwd = process.cwd();
+        if (openDesktopApp(app)) {
+          ctx?.ui?.notify?.(
+            `Opening the Privateer desktop app — same login and per-folder defaults as this terminal. ` +
+              `File ▸ Spawn Privateer at… points a window at ${cwd}.`,
+            "info",
+          );
+        } else {
+          ctx?.ui?.notify?.(`Could not launch ${app} — open it yourself and this terminal keeps working.`, "error");
+        }
+        return;
+      }
+
+      const url = desktopDownloadUrl();
+      const alt = desktopDownloadAltUrl(); // the other Mac build — see desktopApp.ts
+      ctx?.ui?.notify?.(
+        url
+          ? `The Privateer desktop app isn't installed here. Download: ${url}${alt ? ` (other Macs: ${alt})` : ""} — ` +
+              `it reads the same ~/.privateer, so it starts already signed in with your models and connectors.`
+          : `The desktop app ships for macOS and Windows only — on this platform the terminal agent is the app.`,
+        "info",
+      );
+    },
+  });
+}

package/extensions/privateer-hints.ts

@@ -25,6 +25,7 @@ import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { keyText } from "@earendil-works/pi-coding-agent";
 import { configPath, globalDir } from "../src/config/paths.ts";
+import { desktopAppPath } from "../src/config/desktopApp.ts";
 
 const FIRST_MS = 6_000; // a turn shorter than this never shows a tip
 const EVERY_MS = 12_000;
@@ -76,9 +77,28 @@ const HINTS: Array<() => string> = [
       ? `${k} is push-to-talk — /speak on reads the answer back`
       : `/talk types what you say — /speak on reads the answer back`;
   },
+  () => (haveDesktopApp() ? `/desktop opens the Privateer desktop app — same login, same folder defaults` : ""),
   () => `these tips are /hints — /hints off silences them`,
 ];
 
+// A hint returns "" when it doesn't apply to THIS machine, and the rotation skips
+// it. The desktop tip is the case that needs it: naming a command for an app the
+// user has is discoverability, advertising one they haven't is an ad. Memoised
+// because the rotation asks every 12 s and the answer is a stat() on a path that
+// doesn't change under a running terminal (installing the app mid-session is worth
+// a restart, not a filesystem poll).
+let desktopSeen: boolean | undefined;
+function haveDesktopApp(): boolean {
+  if (desktopSeen === undefined) {
+    try {
+      desktopSeen = desktopAppPath() !== null;
+    } catch {
+      desktopSeen = false;
+    }
+  }
+  return desktopSeen;
+}
+
 // Default ON: absent file, absent block, or unreadable JSON all mean enabled.
 // Only an explicit { hints: { enabled: false } } turns the rotation off.
 function hintsEnabled(): boolean {
@@ -119,9 +139,20 @@ export default function privateerHints(pi: any): void {
     if (restoreDefault) uiRef?.setWorkingMessage?.();
   };
 
+  // The next hint that applies here, advancing the cursor past any that opted out.
+  // Bounded by the list length, so an all-empty list ends the rotation instead of
+  // spinning through it forever.
+  const nextHint = (): string => {
+    for (let i = 0; i < HINTS.length; i++) {
+      const text = HINTS[cursor++ % HINTS.length]();
+      if (text) return text;
+    }
+    return "";
+  };
+
   const showNext = (): void => {
-    const hint = HINTS[cursor % HINTS.length]();
-    cursor++;
+    const hint = nextHint();
+    if (!hint) return; // nothing applies on this machine — leave "Working..." alone
     uiRef?.setWorkingMessage?.(`Working... · tip: ${hint}`);
     timer = setTimeout(showNext, EVERY_MS);
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "privateer-agent",
-  "version": "0.12.14",
+  "version": "0.12.15",
   "description": "Privacy-first terminal coding agent — bring your own model across 20 providers (Anthropic, OpenAI, OpenRouter, Google, local Ollama…). Safe-by-default permissions, MCP, sub-agents, workflows, and verifiable TEE inference. Built on the Pi toolkit.",
   "type": "module",
   "license": "MIT",

package/src/config/desktopApp.ts

@@ -0,0 +1,138 @@
+// Where the Privateer DESKTOP app lives on this machine, and how to bring it up.
+//
+// The desktop app and this terminal are two front ends over one home: both read
+// ~/.privateer, so they share the account login, the model config, the MCP catalog
+// and the per-folder spawn defaults (config/spawns.ts). That makes "open the app"
+// a genuinely useful thing for a terminal to offer — nothing is handed over, the
+// state is already common — which is what /desktop (extensions/privateer-desktop.ts)
+// does, and what the working-line tip in privateer-hints.ts points at.
+//
+// WHY DETECTION AND NOT JUST A DOWNLOAD LINK. A tip that advertises software the
+// user hasn't got is an ad; one that names a command for software they HAVE is
+// discoverability. So both consumers ask this module first, and the hint stays
+// silent on a machine with no app installed.
+//
+// NO FOLDER HANDOFF. The app takes no path argument today — its second-instance
+// handler just focuses the running window (desktop/src/main/main.mjs) — so /desktop
+// opens the app, and the user picks this folder from File ▸ Spawn Privateer at…,
+// where the spawn record this terminal already shares makes it start on the same
+// model and connectors. If the app ever learns a folder argv, this is the one place
+// that has to change.
+//
+// IMPORT-SAFETY: node builtins only, no Pi imports, no side effects — safe from an
+// extension under jiti and from a pre-boot entry alike.
+
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+
+/** Per-platform download pages (README ▸ Desktop app). No Linux build exists. */
+const DOWNLOAD_MAC = "https://privateer.pro/download/mac";
+const DOWNLOAD_MAC_INTEL = "https://privateer.pro/download/mac-intel";
+const DOWNLOAD_WINDOWS = "https://privateer.pro/download/windows";
+
+/**
+ * The download page to lead with on THIS machine, or null where we ship no desktop
+ * build. macOS is split by CPU family — the arm64 dmg won't run on an Intel Mac —
+ * and process.arch is the interpreter's answer, not the machine's: an Apple-silicon
+ * Mac running a Rosetta node reports x64 and would be led to the Intel build. That
+ * is survivable rather than solved (detecting the translation means shelling out to
+ * `sysctl sysctl.proc_translated` for one link) because the OTHER build is offered
+ * alongside it — see desktopDownloadAltUrl.
+ */
+export function desktopDownloadUrl(
+  platform: NodeJS.Platform = process.platform,
+  arch: string = process.arch,
+): string | null {
+  if (platform === "darwin") return arch === "x64" ? DOWNLOAD_MAC_INTEL : DOWNLOAD_MAC;
+  if (platform === "win32") return DOWNLOAD_WINDOWS;
+  return null; // electron-builder.yml targets mac + win only
+}
+
+/**
+ * The macOS build for the OTHER CPU family, so a Mac user is never one wrong arch
+ * away from a download that won't launch. Null everywhere else: Windows ships one
+ * x64 installer and there is no Linux build at all.
+ */
+export function desktopDownloadAltUrl(
+  platform: NodeJS.Platform = process.platform,
+  arch: string = process.arch,
+): string | null {
+  if (platform !== "darwin") return null;
+  return arch === "x64" ? DOWNLOAD_MAC : DOWNLOAD_MAC_INTEL;
+}
+
+/**
+ * The installed app, or null. Ordered by confidence:
+ *
+ *  1. OUR OWN interpreter, when the terminal is running on the app's bundled Node.
+ *     The desktop's CLI shim runs `privateer` through the app binary itself with
+ *     ELECTRON_RUN_AS_NODE=1 (desktop/src/main/cliShim.mjs), so process.execPath IS
+ *     the app — and it's the copy the user actually installed, wherever they put it.
+ *  2. The standard install locations. macOS drag-install goes to /Applications or
+ *     ~/Applications; the Windows installer is per-user NSIS (perMachine: false) so
+ *     %LOCALAPPDATA%\Programs\Privateer is the default, with Program Files covered
+ *     for an install that chose it (allowToChangeInstallationDirectory: true).
+ *
+ * A user who installed somewhere else entirely reads as "not installed" — which
+ * costs them a download link they don't need, and never a wrong app launched.
+ */
+export function desktopAppPath(
+  platform: NodeJS.Platform = process.platform,
+  env: Record<string, string | undefined> = process.env,
+  execPath: string = process.execPath,
+): string | null {
+  const hit = (p: string): string | null => (p && existsSync(p) ? p : null);
+
+  if (platform === "darwin") {
+    // …/Privateer.app/Contents/MacOS/Privateer → …/Privateer.app
+    const marker = "/Privateer.app/";
+    const at = execPath.indexOf(marker);
+    if (at >= 0) {
+      const bundle = hit(execPath.slice(0, at + marker.length - 1));
+      if (bundle) return bundle;
+    }
+    return hit("/Applications/Privateer.app") ?? hit(join(homedir(), "Applications", "Privateer.app"));
+  }
+
+  if (platform === "win32") {
+    if (/^privateer\.exe$/i.test(basename(execPath))) {
+      const self = hit(execPath);
+      if (self) return self;
+    }
+    const local = env.LOCALAPPDATA;
+    const files = env.ProgramFiles;
+    return (
+      (local ? hit(join(local, "Programs", "Privateer", "Privateer.exe")) : null) ??
+      (files ? hit(join(files, "Privateer", "Privateer.exe")) : null)
+    );
+  }
+
+  return null;
+}
+
+/**
+ * Launch (or focus) the desktop app. Best-effort and never throws — the caller
+ * reports the failure as text, the way openBrowser.ts does.
+ *
+ * ELECTRON_RUN_AS_NODE IS STRIPPED, and that is load-bearing rather than tidy: when
+ * this terminal was itself started by the desktop's CLI shim, that variable is set
+ * in our environment, and a child inheriting it starts the app binary as a bare Node
+ * that exits without ever drawing a window. `open` goes through LaunchServices and
+ * wouldn't pass it on anyway; the Windows path spawns the exe directly and would.
+ */
+export function openDesktopApp(appPath: string, platform: NodeJS.Platform = process.platform): boolean {
+  const { ELECTRON_RUN_AS_NODE: _drop, ...env } = process.env;
+  try {
+    const child =
+      platform === "darwin"
+        ? spawn("open", ["-a", appPath], { detached: true, stdio: "ignore", env })
+        : spawn(appPath, [], { detached: true, stdio: "ignore", env });
+    child.on("error", () => {}); // a spawn failure must not raise on the event loop
+    child.unref(); // never hold the CLI's exit open
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/config/moatManifest.json

@@ -11,6 +11,7 @@
     { "name": "privateer-privacy", "entry": "extensions/privateer-privacy.ts", "note": "pi-privacy + account tier resolver" },
     { "name": "privateer-connect", "entry": "extensions/privateer-connect.ts", "note": "/connect — MCP connector manager" },
     { "name": "privateer-media", "entry": "extensions/privateer-media.ts", "note": "image/video/speech/music + ffmpeg compose" },
+    { "name": "privateer-desktop", "entry": "extensions/privateer-desktop.ts", "note": "/desktop — open the Privateer desktop app" },
     { "name": "privateer-hints", "entry": "extensions/privateer-hints.ts", "note": "rotating tips in the working line + /hints" },
     { "name": "privateer-update", "entry": "extensions/privateer-update.ts", "note": "tool pack updates in place — banner flag + /update" },
     { "name": "privateer-speak", "entry": "extensions/privateer-speak.ts", "note": "spoken responses (/speak) + voice input (/talk) — pi-speak + confidential account TTS/STT" },