privateer-agent 0.14.6 → 0.15.0

package/src/remote/mcpControl.ts

@@ -5,13 +5,13 @@
  * relay (the harbor today; an interactive terminal by the same shape).
  *
  * The client itself can NEVER run MCP — a browser tab / RN runtime can't spawn a
- * stdio child or hold the adapter. So "serving MCP to phone/web" means MANAGING the
+ * stdio child or hold a server connection. So "serving MCP to phone/web" means MANAGING the
  * config here, on a host that executes it. This control owns that config.
  *
  * SAME FILE MODEL AS THE DESKTOP (treeview/desktop/src/main/mcpService.ts): the
  * source of truth is `${agentDir}/mcp-desktop.json` — every server with an `enabled`
  * flag — and from it we PROJECT the standard `${agentDir}/mcp.json` (enabled servers
- * only, `{mcpServers:{}}` shape) that pi-mcp-adapter reads. Sharing those two files
+ * only, `{mcpServers:{}}` shape) that Pi's built-in MCP support reads. Sharing those two files
  * means a machine has ONE coherent MCP config whether it was edited from the desktop
  * over IPC or from the phone over the relay.
  *
@@ -43,15 +43,16 @@ import { writeFileAtomic } from "../util/atomicWrite.ts";
 export type McpTransport = "stdio" | "http";
 
 /**
- * How an HTTP connector authenticates — our vocabulary, projected onto the adapter's
- * `auth` field. "none" is a server that needs no credential at all (or carries one
- * entirely in custom headers); stdio connectors are always "none".
+ * How an HTTP connector authenticates — our vocabulary, kept in mcp-desktop.json and on
+ * the relay, and projected onto Pi's config (see toPiServerEntry). "none" is a server that
+ * needs no credential at all (or carries one entirely in custom headers); stdio
+ * connectors are always "none".
  */
 export type McpAuth = "oauth" | "bearer" | "none";
 
 // One server as stored in the source file (mcp-desktop.json). Mirrors the desktop's
-// SourceEntry: the standard fields the adapter needs plus our `enabled` flag.
-interface SourceEntry {
+// SourceEntry: the standard server fields plus our auth vocabulary and `enabled` flag.
+export interface SourceEntry {
   transport?: McpTransport;
   command?: string;
   args?: string[];
@@ -63,7 +64,7 @@ interface SourceEntry {
   bearerTokenEnv?: string;
   // LEGACY, read-only: entries written before `auth` existed carry a boolean here.
   // authOf() folds it in; nothing new ever writes it, and project() never emits it
-  // (the adapter's own `oauth` field is an OAuthConfig object, not a boolean).
+  // (Pi's own `oauth` field is an OAuthConfig object, not a boolean).
   oauth?: boolean;
   enabled?: boolean;
 }
@@ -78,14 +79,10 @@ function isAuth(v: unknown): v is McpAuth {
 
 // What this entry will actually do when it connects. Explicit `auth` wins; a bearer
 // token implies bearer; a legacy `oauth: false` means no auth; otherwise HTTP servers
-// auto-detect OAuth, which is the adapter's own default.
-//
-// The headers rule mirrors pi-mcp-adapter's supportsOAuth(): "configured custom headers
-// take precedence over implicit OAuth auto-detection." Without this we'd project an
-// EXPLICIT auth:"oauth" for a headers-carrying entry, and the adapter checks
-// auth === "oauth" BEFORE its headers check — so we'd force OAuth on exactly the
-// connectors it means to skip it for. Only implicit auth defers to headers; an explicit
-// `auth` from the user still wins.
+// auto-detect OAuth, which is Pi's own behaviour (sign-in is offered when the server
+// answers 401). Only implicit auth defers to custom headers — an entry that carries its
+// credential in a header isn't an OAuth connector — while an explicit `auth` from the
+// user still wins.
 function authOf(e: SourceEntry, transport: McpTransport): McpAuth {
   if (transport !== "http") return "none";
   if (isAuth(e.auth)) return e.auth;
@@ -139,6 +136,10 @@ export interface McpDraft {
 }
 
 export interface McpControl {
+  // Re-write mcp.json from mcp-desktop.json. Run once at launch by
+  // migrateMcpProjection, for a file an older release wrote in pi-mcp-adapter's format.
+  // `adopt`: projection entries to take into mcp-desktop.json first when it lacks them.
+  reproject(adopt?: Record<string, unknown>): void;
   // Every managed server, non-secret projection. Enabled or not — the app shows
   // disabled connectors so they can be toggled back on.
   list(): RemoteMcpServer[];
@@ -169,6 +170,139 @@ function cleanArgs(v: unknown): string[] | undefined {
   return v.map((x) => String(x ?? "")).filter((s) => s.length > 0);
 }
 
+// Pi's server-name rule (core/mcp-servers.js), and an environment variable name.
+const SERVER_NAME = /^[A-Za-z0-9_-]+$/;
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+function isSseUrl(url: string): boolean {
+  try {
+    return /\/sse\/?$/i.test(new URL(url).pathname);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Carry a value written for pi-mcp-adapter into Pi's config-value syntax, meaning
+ * exactly what it meant before.
+ *
+ * Every value here — env, headers, a bearer token — was typed for the adapter, and
+ * the app, /connect and the desktop all still write that vocabulary:
+ *   • `${VAR}`, `$env:VAR` and `{env:VAR}` read the environment; any other `$` is a
+ *     literal `$`.
+ *   • A leading `!` runs the rest as a shell command; `!!` is a literal `!`.
+ * Pi (core/resolve-config-value.js) reads `${VAR}` and also bare `$VAR`, runs a
+ * leading `!`, and escapes with `$$` and `$!`. So the references become `${VAR}`,
+ * every other `$` is doubled (a token like `pa$word` would otherwise lose `$word`),
+ * and `!!x` becomes `$!x`. A `!command` stays a command, as it was.
+ *
+ * One difference stays: an unset variable was "" for the adapter, and makes Pi report
+ * the server as misconfigured — a louder failure for the same broken config.
+ */
+export function toPiConfigValue(value: string): string {
+  // "!!x" is a literal "!" then x, with x's references still read (never a command).
+  if (value.startsWith("!!")) return `$!${references(value.slice(2))}`;
+  if (value.startsWith("!")) return value;
+  return references(value);
+}
+
+// The adapter's three reference forms as Pi's `${VAR}`; every other `$` literal.
+function references(value: string): string {
+  const literal = (text: string) => text.replace(/\$/g, "$$$$");
+  let out = "";
+  let last = 0;
+  for (const m of value.matchAll(/\$\{(\w+)\}|\$env:(\w+)|\{env:(\w+)\}/g)) {
+    out += literal(value.slice(last, m.index)) + "${" + (m[1] ?? m[2] ?? m[3]) + "}";
+    last = m.index! + m[0].length;
+  }
+  return out + literal(value.slice(last));
+}
+
+function piConfigValues(values: Record<string, string>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(values)) out[k] = toPiConfigValue(String(v ?? ""));
+  return out;
+}
+
+/**
+ * A bearer token as a whole Authorization header value. A command token (`!cmd`)
+ * printed only the token for the adapter, which added "Bearer "; Pi runs a command
+ * only as the WHOLE value, so the prefix moves inside it.
+ */
+function bearerHeader(token: string): string {
+  if (token.startsWith("!") && !token.startsWith("!!")) return `!printf 'Bearer %s' "$(${token.slice(1)})"`;
+  return `Bearer ${toPiConfigValue(token)}`;
+}
+
+/**
+ * One-time upgrade of a projection written for pi-mcp-adapter. Its marker is the
+ * `settings.toolPrefix` pin every earlier release wrote; such a file carries `auth`
+ * strings and `bearerToken` fields that Pi rejects, so every HTTP connector in it would
+ * vanish. Re-projecting from mcp-desktop.json rewrites it in Pi's format. A file
+ * without the marker — Pi's own, or hand-written — is left alone.
+ */
+export function migrateMcpProjection(dir: () => string = agentDir): boolean {
+  let raw: any;
+  try {
+    raw = JSON.parse(readFileSync(join(dir(), "mcp.json"), "utf8"));
+    if (raw?.settings?.toolPrefix === undefined) return false;
+  } catch {
+    return false;
+  }
+  // A server someone added to mcp.json by hand never reached mcp-desktop.json, and
+  // re-projecting from that file alone would drop it. Adopt those first.
+  makeMcpControl({ dir }).reproject(raw?.mcpServers ?? {});
+  return true;
+}
+
+// Legacy SSE endpoints of servers that also serve streamable HTTP, which is all Pi
+// speaks. A connector saved with one of these (the catalog shipped them) is moved to
+// the streamable URL wherever it is projected, so it keeps working without a re-save.
+const LEGACY_SSE_URLS: Record<string, string> = {
+  "https://mcp.atlassian.com/v1/sse": "https://mcp.atlassian.com/v1/mcp",
+  "https://mcp.asana.com/sse": "https://mcp.asana.com/mcp",
+  "https://mcp.linear.app/sse": "https://mcp.linear.app/mcp",
+};
+
+export function upgradeLegacyUrl(url: string): string {
+  return LEGACY_SSE_URLS[url.replace(/\/$/, "")] ?? url;
+}
+
+// One managed entry as a Pi `mcpServers` entry. Exported for the desktop's connector
+// manager (treeview desktop/src/main/mcpService.ts), which writes the same files and
+// must write them the same way. Built field by field rather than
+// spread, because our vocabulary and Pi's differ:
+//
+//   • Pi has no bearer field. A static token becomes an `Authorization` header, and a
+//     token read from the environment becomes "Bearer ${VAR}". A header named
+//     Authorization is also what tells Pi NOT to start OAuth for the server.
+//   • Pi's `auth` is `{ provider }` — a Pi /login provider's token — not our
+//     "oauth" | "bearer" | "none". Any other value makes Pi reject the whole entry, so
+//     ours never reaches the file. OAuth needs no field at all: Pi offers sign-in when
+//     a server without an Authorization header answers 401.
+//   • Pi and the adapter both expand env and header values, with different syntax:
+//     each value is carried over so it means what it meant (toPiConfigValue). Copied
+//     verbatim, a token containing "$" would be mangled by Pi's bare-$VAR rule.
+export function toPiServerEntry(e: SourceEntry): Record<string, unknown> {
+  const transport: McpTransport = e.transport ?? (e.url ? "http" : "stdio");
+  const std: Record<string, unknown> = {};
+  if (transport === "stdio") {
+    if (e.command) std.command = e.command;
+    if (e.args?.length) std.args = e.args;
+    if (e.env && Object.keys(e.env).length > 0) std.env = piConfigValues(e.env);
+  } else {
+    if (e.url) std.url = upgradeLegacyUrl(e.url);
+    const headers: Record<string, string> = piConfigValues(e.headers ?? {});
+    if (authOf(e, transport) === "bearer") {
+      // A stored token wins over the env var name.
+      if (e.bearerToken) headers.Authorization = bearerHeader(e.bearerToken);
+      else if (e.bearerTokenEnv && ENV_NAME.test(e.bearerTokenEnv)) headers.Authorization = `Bearer \${${e.bearerTokenEnv}}`;
+    }
+    if (Object.keys(headers).length > 0) std.headers = headers;
+  }
+  return std;
+}
+
 export function makeMcpControl(opts?: {
   // Override the source/projection dir (tests). Defaults to the shared agent dir, so
   // this control and the desktop's mcpService edit the SAME two files.
@@ -205,59 +339,21 @@ export function makeMcpControl(opts?: {
     project(src);
   }
 
-  // Project the enabled servers into the standard mcp.json the adapter reads. An
-  // entry with no explicit transport is treated as stdio if it has a command, http
-  // if it has a url — matching the adapter's own inference.
+  // Project the servers into the standard mcp.json Pi reads. An entry with no
+  // explicit transport is treated as stdio if it has a command, http if it has a url —
+  // matching Pi's own inference.
   //
-  // `toolPrefix` is pinned rather than left to the adapter's default because a
-  // routine's "<server>__<tool>" selector is translated into a REGISTERED tool name
-  // before it can grant anything (src/mcp/toolNames.ts), and that translation depends
-  // on the mode. "server" is the adapter's own default, so pinning it changes nothing
-  // today and stops a future default flip from silently voiding every allow-list.
+  // A disabled server is written with Pi's own `enabled: false` rather than left out:
+  // Pi keeps it listed (and skips connecting it), and `mcp login` can still find it —
+  // a desktop window may activate a connector that is off by default and need to sign
+  // in to it.
   function project(src: SourceFile): void {
     const mcpServers: Record<string, unknown> = {};
     for (const [name, e] of Object.entries(src.servers)) {
-      if (e.enabled === false) continue;
-      mcpServers[name] = toStandard(e);
+      mcpServers[name] = e.enabled === false ? { ...toPiServerEntry(e), enabled: false } : toPiServerEntry(e);
     }
     mkdirSync(dirname(projectionPath()), { recursive: true });
-    writeFileAtomic(
-      projectionPath(),
-      JSON.stringify({ mcpServers, settings: { toolPrefix: "server" } }, null, 2) + "\n",
-    );
-  }
-
-  // One managed entry as pi-mcp-adapter's ServerEntry. Built field by field rather
-  // than spread, because our vocabulary and the adapter's differ in two places that
-  // matter: our `auth: "none"` is its `auth: false`, and our legacy boolean `oauth`
-  // collides with its `oauth` (an OAuthConfig OBJECT) and must never reach the file.
-  //
-  // Getting `auth` right is load-bearing, not cosmetic. The adapter only attaches an
-  // Authorization header when `auth === "bearer"` (server-manager.ts), and its
-  // supportsOAuth() refuses OAuth outright once custom headers are configured — so an
-  // omitted `auth` silently means "no bearer token was ever sent".
-  function toStandard(e: SourceEntry): Record<string, unknown> {
-    const transport: McpTransport = e.transport ?? (e.url ? "http" : "stdio");
-    const std: Record<string, unknown> = {};
-    if (transport === "stdio") {
-      if (e.command) std.command = e.command;
-      if (e.args?.length) std.args = e.args;
-    } else {
-      if (e.url) std.url = e.url;
-      if (e.headers && Object.keys(e.headers).length > 0) std.headers = e.headers;
-      const auth = authOf(e, transport);
-      if (auth === "bearer") {
-        std.auth = "bearer";
-        if (e.bearerToken) std.bearerToken = e.bearerToken;
-        if (e.bearerTokenEnv) std.bearerTokenEnv = e.bearerTokenEnv;
-      } else if (auth === "oauth") {
-        std.auth = "oauth";
-      } else {
-        std.auth = false;
-      }
-    }
-    if (e.env && Object.keys(e.env).length > 0) std.env = e.env;
-    return std;
+    writeFileAtomic(projectionPath(), JSON.stringify({ mcpServers }, null, 2) + "\n");
   }
 
   function toRemote(name: string, e: SourceEntry): RemoteMcpServer {
@@ -306,6 +402,18 @@ export function makeMcpControl(opts?: {
   }
 
   return {
+    reproject(adopt?: Record<string, unknown>): void {
+      const src = readSource();
+      let added = false;
+      for (const [name, entry] of Object.entries(adopt ?? {})) {
+        if (src.servers[name] || !entry || typeof entry !== "object") continue;
+        src.servers[name] = { ...(entry as SourceEntry), enabled: true };
+        added = true;
+      }
+      if (added) writeSource(src);
+      else project(src);
+    },
+
     list(): RemoteMcpServer[] {
       const src = readSource();
       return Object.entries(src.servers).map(([name, e]) => toRemote(name, e));
@@ -314,6 +422,9 @@ export function makeMcpControl(opts?: {
     save(draft: McpDraft): { ok: boolean; message?: string } {
       const name = String(draft?.name ?? "").trim();
       if (!name) return { ok: false, message: "A connector needs a name." };
+      // Pi's rule for server names; anything else is skipped as invalid at connect time.
+      if (!SERVER_NAME.test(name))
+        return { ok: false, message: "A connector name may use only letters, digits, \"-\" and \"_\"." };
       if (draft.transport !== undefined && !isTransport(draft.transport))
         return { ok: false, message: "Unknown transport." };
       if (draft.auth !== undefined && !isAuth(draft.auth))
@@ -342,6 +453,9 @@ export function makeMcpControl(opts?: {
         if (!entry.command) return { ok: false, message: "A local (stdio) connector needs a command." };
       } else {
         if (draft.url !== undefined) entry.url = String(draft.url).trim();
+        // A connector saved with a legacy SSE endpoint before Pi: move it on, rather
+        // than refuse every later edit of it below.
+        if (entry.url) entry.url = upgradeLegacyUrl(entry.url);
         // `auth` is authoritative; the legacy boolean is honoured only when it isn't
         // sent, so an old app build keeps working without being able to override.
         if (draft.auth !== undefined) entry.auth = draft.auth;
@@ -362,9 +476,9 @@ export function makeMcpControl(opts?: {
           else delete entry.headers;
         }
         // A token that arrived without an explicit `auth` means bearer — otherwise the
-        // adapter stores the token and never sends it (it only sets the Authorization
-        // header when auth === "bearer"), which reads to the user as "my token is
-        // saved and the connector still 401s".
+        // token is stored and never projected into an Authorization header (toPiServerEntry
+        // only sends it for bearer), which reads to the user as "my token is saved and
+        // the connector still 401s".
         if (draft.auth === undefined && (entry.bearerToken || entry.bearerTokenEnv)) entry.auth = "bearer";
         // Once `auth` is set, the legacy boolean is noise that authOf would have to
         // keep tie-breaking. Drop it.
@@ -372,6 +486,15 @@ export function makeMcpControl(opts?: {
         delete entry.command;
         delete entry.args;
         if (!entry.url) return { ok: false, message: "A remote (http) connector needs a URL." };
+        // Pi speaks streamable HTTP only. An SSE endpoint would save and then fail on
+        // every connect, so say so now — most servers serve streamable HTTP at /mcp.
+        if (isSseUrl(entry.url))
+          return {
+            ok: false,
+            message: "That looks like a legacy SSE endpoint, which isn't supported. Use the server's streamable HTTP URL (often ending in /mcp).",
+          };
+        if (entry.bearerTokenEnv && !ENV_NAME.test(entry.bearerTokenEnv))
+          return { ok: false, message: "The token variable must be an environment variable name, like GITHUB_TOKEN." };
         if (authOf(entry, "http") === "bearer" && !entry.bearerToken && !entry.bearerTokenEnv)
           return { ok: false, message: "A bearer connector needs a token, or the name of an env var holding one." };
       }

package/src/remote/relayClient.ts

@@ -1303,7 +1303,7 @@ export class RelayClient {
   // `builtIn` + `managed` describe the MOAT, which is deliberately absent from
   // `installed` (it never enters settings "packages"). Without them the app's Browse
   // tab — an unfiltered npm `keywords:pi-package` search — offers Add on packages we
-  // already ship: pi-mcp-adapter, pi-subagents and the rpiv packs are on its first
+  // already ship (or retired): pi-mcp-adapter, pi-subagents and the rpiv packs are on its first
   // page. Every one of those round-trips to extensionsControl.add() only to come back
   // refused ("managed by Privateer"), and until it does the row reads as *not*
   // installed, which is the opposite of the truth. So:

package/src/routines/toolSelect.ts

@@ -4,10 +4,10 @@
 // or a per-server wildcard "<server>__*" — everything else is a builtin allow-list
 // entry.
 //
-// NOTE the selector is NOT the name Pi registers. pi-mcp-adapter names a tool
-// "<serverPrefix>_<tool>" (one underscore), and Pi's `tools:` option is an exact-match
-// Set — so a selector must be TRANSLATED before it can grant anything. That
-// translation lives in ../mcp/toolNames.ts; this module only splits and matches.
+// NOTE the selector is NOT the name Pi registers. Pi names an MCP tool
+// "mcp__<server>__<tool>", so a selector must be TRANSLATED before it can grant
+// anything. That translation lives in ../mcp/toolNames.ts; this module only splits and
+// matches.
 
 export interface RoutineToolSplit {
   // Builtin tool names (read, glob, ...). Empty → caller falls back to the safe set.

package/src/harbor/buildLock.ts

@@ -1,19 +0,0 @@
-// Session CONSTRUCTION is serialized across the whole process. pi-mcp-adapter decides
-// which MCP tools to register directly at extension-activation time, and the only knob
-// for that is the MCP_DIRECT_TOOLS env var — process-global state we set per run to
-// keep each unattended session to its own connector allow-list. Serializing the
-// (short) build window is what stops two concurrent builds from reading each other's
-// value. Prompting is NOT serialized — only the build.
-//
-// Lifted out of harbor/index.ts so the channels runtime can share the SAME lock once
-// it runs inside the harbor: two owners each with their own lock would serialize
-// against themselves and race against each other, which is exactly the bug the lock
-// exists to prevent.
-
-let buildLock: Promise<unknown> = Promise.resolve();
-
-export function serializeBuild<T>(fn: () => Promise<T>): Promise<T> {
-  const run = buildLock.then(fn, fn);
-  buildLock = run.catch(() => {});
-  return run;
-}