privateer-agent 0.8.2 → 0.9.1

package/src/harbor/ipc.ts

@@ -22,6 +22,28 @@ export type IpcRequest =
   | { cmd: "run-now"; idOrName: string }
   | { cmd: "reload" };
 
+/**
+ * The harbor's view of its own relay connection, reported by `status`.
+ *
+ * A harbor answering on this socket is running; that is NOT the same as being
+ * reachable from the app, which needs the relay socket up (the server drops a
+ * terminal from its presence registry ~60s after it stops hearing from it). The two
+ * used to be conflated — "running (answering IPC)" while the app showed the same
+ * harbor as offline — so every liveness report carries both now.
+ */
+export interface RelayStatus {
+  /** The relay terminal id the app looks for ("routines-…"). */
+  termId: string;
+  /** Socket open right now, i.e. the app can see and drive this harbor. */
+  connected: boolean;
+  /** Seconds the current connection has been up. */
+  upSec?: number;
+  /** Seconds since the server last sent anything (frame, ping or pong). */
+  quietSec?: number;
+  /** Why it isn't connected, when we know: signed out, turned off from the app, … */
+  detail?: string;
+}
+
 export interface IpcResponse {
   ok: boolean;
   message?: string;
@@ -29,6 +51,8 @@ export interface IpcResponse {
   // Harbor liveness/uptime for `status`.
   pid?: number;
   uptimeSec?: number;
+  // Relay reachability for `status` — see RelayStatus.
+  relay?: RelayStatus;
 }
 
 export type IpcHandler = (req: IpcRequest) => Promise<IpcResponse> | IpcResponse;
@@ -164,6 +188,32 @@ export class HarborAlreadyRunningError extends Error {
   }
 }
 
+// One-line, human rendering of a status reply's relay block — shared by
+// `privateer harbor status` and the second-instance notice so both tell the same
+// story. `undefined` means the harbor answering us predates this field.
+export function describeRelay(relay?: RelayStatus): string {
+  if (!relay) return "unknown (this harbor is an older build)";
+  if (!relay.connected) {
+    return `NOT connected — the app shows this Harbor as inactive${relay.detail ? ` (${relay.detail})` : ""}`;
+  }
+  const up = typeof relay.upSec === "number" ? `, up ${formatDuration(relay.upSec)}` : "";
+  // A connected socket the server hasn't spoken on in a while is the half-open shape;
+  // the watchdog drops it within ~75s, so say so rather than reporting a flat "connected".
+  const quiet = typeof relay.quietSec === "number" && relay.quietSec > 40 ? `, quiet for ${relay.quietSec}s — checking` : "";
+  return `connected — drivable from the Privateer app (${relay.termId}${up}${quiet})`;
+}
+
+export function formatDuration(totalSec: number): string {
+  const s = Math.max(0, Math.round(totalSec));
+  const d = Math.floor(s / 86400);
+  const h = Math.floor((s % 86400) / 3600);
+  const m = Math.floor((s % 3600) / 60);
+  if (d) return `${d}d ${h}h`;
+  if (h) return `${h}h ${m}m`;
+  if (m) return `${m}m`;
+  return `${s}s`;
+}
+
 // Convenience: is the harbor reachable right now?
 export async function harborIsRunning(): Promise<boolean> {
   try {

package/src/harbor/service.ts

@@ -12,7 +12,7 @@ import { homedir } from "node:os";
 import { join, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { globalDir } from "../config/paths.ts";
-import { harborIsRunning } from "./ipc.ts";
+import { harborIsRunning, sendToHarbor, describeRelay, formatDuration, type IpcResponse } from "./ipc.ts";
 
 const LABEL = "pro.privateer.harbor"; // launchd label / reverse-dns id
 const UNIT = "privateer-harbor.service"; // systemd --user unit name
@@ -62,7 +62,13 @@ function xmlEscape(s: string): string {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
 
-function launchdPlist(): string {
+// KeepAlive is `{ SuccessfulExit: false }`, NOT plain `true` — restart on a crash,
+// but leave a CLEAN exit alone. A bare `true` restarts unconditionally, which turns
+// the two clean-exit paths into loops: the harbor that finds another one already
+// holding the machine lock (exit 0 every ~10s, appending the same line to harbor.log
+// forever — this is what produced a 7 MB log of "already running"), and a deliberate
+// shutdown, which launchd would undo. Matches the systemd unit's Restart=on-failure.
+export function launchdPlist(): string {
   const args = [nodeBinaryPath(), harborLauncherPath(), "run"];
   const envVars = forwardedEnv();
   const argXml = args.map((a) => `    <string>${xmlEscape(a)}</string>`).join("\n");
@@ -83,7 +89,10 @@ ${argXml}
 ${envVars.PRIVATEER_HOME || envVars.PRIVATEER_SERVER_URL ? `  <key>EnvironmentVariables</key>\n  <dict>\n${envXml}\n  </dict>\n` : ""}  <key>RunAtLoad</key>
   <true/>
   <key>KeepAlive</key>
-  <true/>
+  <dict>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
   <key>StandardOutPath</key>
   <string>${log}</string>
   <key>StandardErrorPath</key>
@@ -199,6 +208,24 @@ export interface ServiceInfo {
   installed: boolean;
   unitPath: string;
   logPath: string;
+  /** Installed unit predates a fix and should be rewritten — see needsRefresh(). */
+  needsRefresh: boolean;
+}
+
+// Does the INSTALLED unit need rewriting? Deliberately narrow: a full text compare
+// against what we'd generate today would flag every service installed by a different
+// copy of the CLI (a dev checkout resolves a different launcher path), which is not a
+// problem and not something the user should be nagged about. The one thing worth
+// flagging is the pre-fix launchd `KeepAlive: true`, which restarts the harbor even
+// after a clean exit — the log-spam loop described above launchdPlist().
+export function unitNeedsRefresh(platform: NodeJS.Platform, unitPath: string): boolean {
+  if (platform !== "darwin" || !existsSync(unitPath)) return false;
+  try {
+    const plist = readFileSync(unitPath, "utf8");
+    return /<key>KeepAlive<\/key>\s*<true\s*\/>/.test(plist);
+  } catch {
+    return false;
+  }
 }
 
 function unitPathFor(platform: NodeJS.Platform): string {
@@ -216,6 +243,7 @@ export function serviceInfo(): ServiceInfo {
     installed: !!unitPath && existsSync(unitPath),
     unitPath,
     logPath: harborLogPath(),
+    needsRefresh: unitNeedsRefresh(platform, unitPath),
   };
 }
 
@@ -236,20 +264,40 @@ export function uninstallService(): ServiceInfo {
   return serviceInfo();
 }
 
-// Human-readable status line for `privateer harbor status`: whether the service is
-// installed AND whether a harbor is actually answering on the IPC socket right now.
+// Human-readable status for `privateer harbor status`: whether the service is
+// installed, whether a harbor is answering on the IPC socket, and — the part that
+// actually answers "why does the app say inactive?" — whether that harbor is
+// connected to the relay. Answering IPC only proves a local process is alive; the
+// app lists a harbor from the server's presence registry, which a dead relay socket
+// drops within ~60s. Reporting the first as if it implied the second is what made a
+// stale harbor look healthy from the terminal and offline from the phone.
 export async function statusReport(): Promise<string> {
   const info = serviceInfo();
-  const live = await harborIsRunning();
+  let status: IpcResponse | null = null;
+  try {
+    status = await sendToHarbor({ cmd: "status" }, 3_000);
+  } catch {
+    status = null; // not running, or wedged — harborIsRunning() below tells them apart
+  }
+  const live = status ? status.ok : await harborIsRunning();
+  const up = status && typeof status.uptimeSec === "number" ? `, up ${formatDuration(status.uptimeSec)}` : "";
+  const pid = status?.pid ? `pid ${status.pid}${up}` : "answering IPC";
   const lines = [
     `platform:  ${info.platform}${info.supported ? "" : " (auto-start unsupported — run `privateer harbor` manually)"}`,
     `service:   ${info.installed ? `installed (${info.unitPath})` : "not installed"}`,
-    `harbor:    ${live ? "running (answering IPC)" : "not reachable"}`,
-    `logs:      ${info.logPath}`,
+    `harbor:    ${live ? `running (${pid})` : "not reachable"}`,
   ];
+  if (live) lines.push(`relay:     ${describeRelay(status?.relay)}`);
+  lines.push(`logs:      ${info.logPath}`);
   // Surface a stale-unit hint: file present but nothing answering usually means it
   // failed to boot — the log path above is where to look.
   if (info.installed && !live) lines.push("hint:      service is installed but not answering — check the log for a boot error.");
+  if (live && status?.relay && !status.relay.connected) {
+    lines.push("hint:      Harbor is running but not reachable from the app. Restart it (`privateer harbor uninstall && privateer harbor install`) once the cause above is resolved.");
+  }
+  if (info.needsRefresh) {
+    lines.push("hint:      the installed login service restarts Harbor even after a clean exit (older install) — run `privateer harbor install` to refresh it.");
+  }
   return lines.join("\n");
 }
 

package/src/mcp/catalog.ts

@@ -36,6 +36,34 @@ export interface CatalogEntry {
   fill?: string;
   // Where to get the credential, shown as a hint in the form.
   credUrl?: string;
+  // Can this connector run on a HOSTED (Harbor) agent? Leave unset to take the derived
+  // answer from hostedCapable() below; set it explicitly only to say "no" to something
+  // that would otherwise qualify.
+  hosted?: boolean;
+}
+
+/**
+ * Whether an entry can run on a hosted agent, as opposed to a local daemon/desktop.
+ *
+ * The rule is not a preference, it is the runtime: a Harbor tenant is `--read-only`,
+ * `--cap-drop ALL`, has no `uv`/`uvx`/Python/browser, and its home is tmpfs wiped on
+ * every suspend. A stdio entry would have to download and execute unmeasured
+ * third-party code inside an attested enclave at runtime, which defeats the point of
+ * the measurement; and a token-bearing entry would need a durable secret at rest,
+ * which we decided against (Option B — see treeview/docs/HARBOR_CONNECTORS_PLAN.md §2).
+ * What is left is remote HTTP + OAuth.
+ *
+ * The `/connect` picker filters on this (extensions/privateer-connect.ts →
+ * catalogRows) rather than showing 21 options of which 16 cannot work. It shapes the
+ * custom-connector form there too: no local command, no stored token.
+ *
+ * It does NOT gate mcpControl.save() — the app-over-relay path can still write a
+ * connector this returns false for. Fixing that means teaching mcpControl about
+ * hosted mode, which is a bigger change than a picker filter.
+ */
+export function hostedCapable(e: CatalogEntry): boolean {
+  if (e.hosted !== undefined) return e.hosted;
+  return e.transport === "http" && e.oauth === true;
 }
 
 export const MCP_CATALOG: CatalogEntry[] = [
@@ -327,7 +355,10 @@ export function draftFromCatalog(
     draft.args = (e.args ?? []).map((a) => (e.fill && a === e.fill && filled ? filled : a));
   } else {
     draft.url = e.url;
-    draft.oauth = e.oauth ?? true;
+    // Every http entry in this catalog is an OAuth connector. Emit the adapter's own
+    // vocabulary (`auth`) rather than the legacy boolean, so the projection carries
+    // `auth: "oauth"` and not a bogus boolean in the adapter's OAuthConfig slot.
+    draft.auth = (e.oauth ?? true) ? "oauth" : "none";
   }
 
   const keys = Object.keys(e.env ?? {});

package/src/mcp/toolNames.ts

@@ -0,0 +1,177 @@
+/**
+ * Translating a routine's MCP selectors into the tool names Pi will actually honour.
+ *
+ * There are TWO vocabularies here and conflating them is why per-routine connector
+ * allow-lists silently granted nothing:
+ *
+ *  • The SELECTOR vocabulary — "<server>__<tool>" exact, or "<server>__*" for a whole
+ *    server. This is what a routine stores, what the app writes, and what the AI
+ *    drafts. The double underscore is the point: no Pi builtin contains "__", so
+ *    splitRoutineTools can tell a connector selector from a builtin name without a
+ *    lookup table. This vocabulary is STABLE — routines on disk depend on it.
+ *
+ *  • The REGISTERED vocabulary — what pi-mcp-adapter actually names a tool when it
+ *    registers it with Pi: `formatToolName()` → "<serverPrefix>_<tool>", ONE
+ *    underscore, with dashes in the server name folded to underscores. And Pi's
+ *    `tools:` option is an exact-match Set (`allowedToolNames`), so a literal
+ *    "github__*" or even "github__create_issue" handed to it matches nothing at all.
+ *
+ * This module is the translation layer, mirroring pi-mcp-adapter's `getServerPrefix`
+ * / `formatToolName` rather than importing them — the adapter ships as .ts in
+ * node_modules and pulling it into our typecheck is the thing `harbor/index.ts`
+ * already dodges with a variable import specifier. The mirror is four lines and is
+ * pinned by tests/toolSelect.test.ts.
+ *
+ * The other half of the problem: per-tool names only EXIST when direct tools are
+ * enabled. Otherwise the adapter exposes MCP through a single proxy tool named "mcp"
+ * — all servers, all tools, one grant, which is precisely what a per-routine
+ * allow-list is meant to avoid. So callers pair `names` with `directToolsEnv`, which
+ * scopes MCP_DIRECT_TOOLS to exactly the selected server/tool pairs for that one run.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { agentDir } from "../config/paths.ts";
+
+export type PrefixMode = "server" | "none" | "short";
+
+/** Mirrors pi-mcp-adapter's getServerPrefix. */
+export function serverPrefix(serverName: string, mode: PrefixMode): string {
+  if (mode === "none") return "";
+  if (mode === "short") {
+    const short = serverName.replace(/-?mcp$/i, "").replace(/-/g, "_");
+    return short || "mcp";
+  }
+  return serverName.replace(/-/g, "_");
+}
+
+/** Mirrors pi-mcp-adapter's formatToolName. */
+export function formatToolName(toolName: string, serverName: string, mode: PrefixMode): string {
+  const p = serverPrefix(serverName, mode);
+  return p ? `${p}_${toolName}` : toolName;
+}
+
+/** The cached tool inventory the adapter builds after connecting: server → tool names. */
+export type McpInventory = Record<string, string[]>;
+
+export interface ResolveInput {
+  /** "<server>__<tool>" / "<server>__*" selectors, as stored on the routine. */
+  selectors: string[];
+  /** Server → the tool names it exposes, from the adapter's metadata cache. */
+  inventory: McpInventory;
+  /** The adapter's tool-prefix mode (mcp.json → settings.toolPrefix). */
+  prefix: PrefixMode;
+}
+
+export interface ResolvedMcpTools {
+  /** Exact registered tool names to hand to Pi's `tools:` allow-list. */
+  names: string[];
+  /** Servers touched by the selectors — the set that must be reachable this run. */
+  servers: string[];
+  /** MCP_DIRECT_TOOLS entries ("server/tool", or bare "server" for a wildcard). */
+  directToolsEnv: string[];
+  /**
+   * Servers a selector named that the metadata cache knows nothing about. A wildcard
+   * over one of these expands to NOTHING, so the caller must warm the cache before
+   * building the session — see harbor/index.ts. Never silently ignore this.
+   */
+  coldServers: string[];
+  /**
+   * Exact selectors whose server DID report an inventory that doesn't contain that
+   * tool — a typo, or a tool the connector dropped. The name is still granted (it
+   * simply never registers), but the caller should say so rather than let the run
+   * quietly come back thinner than asked for.
+   */
+  unknownTools: string[];
+}
+
+/**
+ * Expand selectors against a known inventory. Pure — the file reads live in
+ * `resolveMcpSelection` below so this stays trivially testable.
+ *
+ * An EXACT selector resolves without the inventory (we can compute the registered
+ * name from the server + tool alone), so a connector whose cache entry is stale still
+ * works. A WILDCARD needs the inventory to enumerate, which is why `coldServers`
+ * exists.
+ */
+export function resolveMcpTools({ selectors, inventory, prefix }: ResolveInput): ResolvedMcpTools {
+  const names: string[] = [];
+  const servers: string[] = [];
+  const directToolsEnv: string[] = [];
+  const coldServers: string[] = [];
+  const unknownTools: string[] = [];
+
+  const push = <T>(arr: T[], v: T) => {
+    if (!arr.includes(v)) arr.push(v);
+  };
+
+  for (const selector of selectors) {
+    const sep = selector.indexOf("__");
+    if (sep <= 0) continue; // not a selector; splitRoutineTools already routed it
+    const server = selector.slice(0, sep);
+    const tool = selector.slice(sep + 2);
+    if (!tool) continue;
+    push(servers, server);
+
+    if (tool === "*") {
+      const known = inventory[server];
+      if (!known || known.length === 0) {
+        push(coldServers, server);
+        continue;
+      }
+      // Bare server name = "every tool on this server" to MCP_DIRECT_TOOLS.
+      push(directToolsEnv, server);
+      for (const t of known) push(names, formatToolName(t, server, prefix));
+      continue;
+    }
+
+    push(names, formatToolName(tool, server, prefix));
+    // MCP_DIRECT_TOOLS matches the ORIGINAL (unprefixed) tool name.
+    push(directToolsEnv, `${server}/${tool}`);
+    const known = inventory[server];
+    if (!known || known.length === 0) push(coldServers, server);
+    else if (!known.includes(tool)) push(unknownTools, selector);
+  }
+
+  return { names, servers, directToolsEnv, coldServers, unknownTools };
+}
+
+/** The adapter's metadata cache, as it lands on disk (agent/mcp-cache.json). */
+export function readMcpInventory(dir: string = agentDir()): McpInventory {
+  const out: McpInventory = {};
+  try {
+    const raw = JSON.parse(readFileSync(join(dir, "mcp-cache.json"), "utf8"));
+    for (const [server, entry] of Object.entries<any>(raw?.servers ?? {})) {
+      const tools = Array.isArray(entry?.tools)
+        ? entry.tools.map((t: any) => String(t?.name ?? "")).filter(Boolean)
+        : [];
+      out[server] = tools;
+    }
+  } catch {
+    /* no cache yet — every selected server is cold */
+  }
+  return out;
+}
+
+/**
+ * The adapter's prefix mode. `mcpControl.project()` pins "server" into the file it
+ * writes, so this is really a guard for a hand-written mcp.json.
+ */
+export function readPrefixMode(dir: string = agentDir()): PrefixMode {
+  try {
+    const raw = JSON.parse(readFileSync(join(dir, "mcp.json"), "utf8"));
+    const mode = raw?.settings?.toolPrefix;
+    if (mode === "server" || mode === "none" || mode === "short") return mode;
+  } catch {
+    /* no config — the adapter's own default */
+  }
+  return "server";
+}
+
+/** Read-from-disk wrapper around resolveMcpTools. */
+export function resolveMcpSelection(selectors: string[], dir: string = agentDir()): ResolvedMcpTools {
+  return resolveMcpTools({
+    selectors,
+    inventory: readMcpInventory(dir),
+    prefix: readPrefixMode(dir),
+  });
+}