privateer-agent 0.9.2 → 0.10.0

package/README.md

@@ -116,8 +116,8 @@ silently. The moat is swappable; the floor under it holds.
 - **Chat-app channels.** Bridge the agent into Telegram, Slack, Discord, or WhatsApp with
   role-based approval — admins can approve actions, members are read-only.
 - **MCP servers, sub-agents & skills.** Connect Model Context Protocol servers (local stdio
-  or remote HTTP with OAuth), delegate work to bounded parallel sub-agents, and drop in
-  skills — all gated like everything else.
+  or remote HTTP with OAuth) with [`/connect`](#connectors--mcp), delegate work to bounded
+  parallel sub-agents, and drop in skills — all gated like everything else.
 - **Zero-Data-Retention surfacing** for OpenRouter — see the selected model's retention
   posture before you send, and pin routing to zero-retention endpoints.
 - **Plan mode**, checkpoint/rewind, session branching, a modal prompt with `/` command and
@@ -376,6 +376,80 @@ the app are write-only — the app can name them but never read them back. Note
 live in plaintext in `config.json` on your machine, and every channel action is appended to
 `~/.privateer/channels-audit.log`.
 
+## Connectors — MCP
+
+Privateer is an **MCP client**. Point it at a [Model Context Protocol](https://modelcontextprotocol.io)
+server and that server's tools become first-class agent tools, gated exactly like the
+built-ins. Two kinds:
+
+| | |
+|---|---|
+| **Local — `stdio`** | Privateer spawns the server as a child process on this machine. Nothing leaves the box except what that server itself chooses to send. |
+| **Remote — `http`** | An `https` endpoint somebody else hosts. It authenticates with `oauth` (you authorize in a browser on **this** machine), a static `bearer` token, or nothing at all. Whatever the agent hands that server leaves your machine — the app shows a "sends data to *host*" badge for exactly this reason. |
+
+### Add one
+
+```
+/connect        # add, enable, disable, or remove connectors
+/mcp            # pi-mcp-adapter's own status view — what actually connected
+```
+
+`/connect` opens a picker over a curated catalog of 21 connectors — GitHub, Slack, Notion,
+Linear, Jira & Confluence, Sentry, Stripe, Asana, Supabase, Figma, Gmail, Google Drive,
+PostgreSQL, Playwright, Filesystem, … — plus a **Custom connector** entry for anything
+else: any stdio command line, or any `https://` URL. Pick one, fill in the token or path it
+asks for, and the adapter reloads in place, so the new tools are live in the session you're
+already sitting in. You can do the same from [the app](#the-privateer-app) or the desktop
+app; all three edit the same files.
+
+### One config, three surfaces
+
+```
+~/.privateer/agent/mcp-desktop.json   # source of truth — every connector, each with `enabled`
+~/.privateer/agent/mcp.json           # projection: enabled connectors only, in the standard
+                                      # { "mcpServers": … } shape the adapter reads
+```
+
+Don't hand-edit the projection — it is rewritten from the source on every change. Edit
+`mcp-desktop.json`, or just use `/connect`.
+
+Both files live in the shared `~/.privateer` home, so a connector you add in the terminal is
+already there for the harbor's unattended routine runs and for the desktop app's windows.
+One machine, one coherent connector config, however you reached it.
+
+### Tools and the moat
+
+By default the adapter exposes MCP through a **single proxy tool named `mcp`** — one grant
+covers every server you've enabled. When a routine carries a per-connector allow-list,
+Privateer scopes that run down to exactly the selected servers and tools instead, each
+registered under its own `<server>_<tool>` name, so an unattended task can hold GitHub's
+`create_issue` without holding all of MCP.
+
+Either way, **every MCP tool goes through the same permission gate as the built-ins.** A
+tool is not trusted because you configured the server it came from.
+
+### Credentials
+
+A connector's secrets — env values, a bearer token, an `Authorization:` header — are written
+in **plaintext** to `mcp-desktop.json` on this machine. That's unavoidable: the adapter has
+to hand the real token to the server. `/connect` masks the field while you type, which is
+shoulder-surfing and screen-share hygiene, not a storage claim. Protect that file the way you
+protect `~/.aws/credentials`.
+
+Editing connectors **from the app** is a different story: over the relay secrets are
+write-only in both directions. A listing returns env/header *names* and which of them are
+set — never a value — and a value you type on your phone is sealed to that terminal's pinned
+key before it leaves the device, so the relay forwards it blind. See
+[What you can do from the app](#what-you-can-do-from-the-app).
+
+A hand-written `.mcp.json` in a project directory is a **protected path**: the agent can be
+asked to edit one, but never does it silently, in any mode.
+
+> **Hosted harbors are OAuth-only by design** — no stdio child processes, no stored tokens,
+> because a hosted tenant's home is tmpfs and a durable secret would have to rest somewhere
+> we could read. In the current preview they carry no connectors at all; mirroring your
+> catalog into a hosted agent isn't wired up yet.
+
 ## Permission modes
 
 | Mode | Behavior |
@@ -424,9 +498,8 @@ Everything below is a **Pi extension** loaded by discovery (see [Built on Pi](#b
 drop your own into `~/.privateer/agent/extensions/` and it loads the same way, gated like the rest.
 
 - **MCP servers** (`pi-mcp-adapter`) — declare them and their tools become first-class, gated
-  like the rest (local stdio, or remote HTTP with interactive OAuth). One catalog at
-  `~/.privateer/agent/mcp-desktop.json` is shared by the CLI, the harbor, and the desktop
-  app, so a machine has one coherent connector config.
+  like the rest (local stdio, or remote HTTP with interactive OAuth). Add them with
+  `/connect`; see [Connectors — MCP](#connectors--mcp).
 - **Sub-agents** (`pi-subagents`) — delegate investigations to bounded parallel agents. Children
   run as headless child processes that **inherit the moat**, so their actions hit the same
   permission gate and their approvals surface on your phone.
@@ -447,6 +520,7 @@ drop your own into `~/.privateer/agent/extensions/` and it loads the same way, g
 | `/verify` | fetch and check the TEE attestation for the current model |
 | `/signin` · `/signout` | sign in to a Privateer account (device flow) / sign out |
 | `/remote-access` | link this terminal to the app and allow it to drive (off by default) |
+| `/connect` · `/mcp` | add, enable, or remove MCP connectors / see what actually connected |
 | `/extensions` | list loaded Pi extensions |
 | `/init` | scaffold a starter `PRIVATEER.md` in this directory |
 | `/update` · `/privateer` | update to the latest release / Privateer status and posture |

package/bin/privateer-acp.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+// Launcher for Privateer's ACP surface — the entry an ACP host (Buzz's `buzz-acp`,
+// Zed, …) spawns and drives over newline-delimited JSON-RPC on stdio.
+//
+// Mirrors bin/privateer-harbor.mjs: load dev keys from the repo .env WITHOUT changing
+// cwd, register tsx so TS resolves regardless of the invocation cwd, then hand off to
+// src/acp/run.ts (which imports ./boot.ts before any Pi code).
+//
+// ⚠️ THE SPAWN CWD IS THE CONFINEMENT ROOT unless `acp.cwd` is set in
+// ~/.privateer/config.json. Whatever directory the host launches this process in is
+// what the permission gate confines tools to — the per-session cwd a host sends in
+// `session/new` does NOT override it (see the header of src/acp/run.ts). A host that
+// spawns from `/` or `$HOME` therefore makes confinement very broad. Set `acp.cwd`
+// when the host's spawn directory isn't the project you mean to scope the agent to.
+//
+// ⚠️ STDOUT IS THE PROTOCOL. Nothing in this process may write non-JSON-RPC bytes to
+// stdout — a single stray line breaks the stream and the host disconnects. Note that
+// process.loadEnvFile and tsx's register() are both silent; keep it that way, and
+// send any diagnostic you add to stderr.
+import { register } from "tsx/esm/api";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const repo = resolve(here, "..");
+
+try {
+  process.loadEnvFile(resolve(repo, ".env"));
+} catch {
+  /* no .env — rely on the ambient environment / ~/.privateer */
+}
+
+// Same reasoning as the harbor: this process loads the moat as in-code factories, so
+// subagent children can't inherit it and `pi` isn't on PATH. Point pi-subagents at
+// our moat-injecting wrapper so any child spawns gated + private with no double-load.
+process.env.PI_SUBAGENT_PI_BINARY ??= resolve(repo, "bin/privateer-subagent.mjs");
+
+register();
+const { runAcp } = await import(resolve(repo, "src/acp/run.ts"));
+await runAcp();

package/bin/privateer-launch.mjs

@@ -122,6 +122,19 @@ else if (sub === "harbor" || sub === "daemon") {
   runToCompletion(NODE_BIN, [...nodeArgs, path.join(REPO, "bin", "privateer-harbor.mjs"), ...args.slice(1)]);
 }
 
+// --- `privateer acp` -------------------------------------------------------
+// Privateer as an Agent Client Protocol server, spawned by an ACP host (Buzz's
+// `buzz-acp`, Zed, …) and driven over newline-delimited JSON-RPC on stdio.
+//
+// ⚠️ STDOUT IS THE PROTOCOL here, so this branch must stay silent: no banner, no
+// patch chatter, no moat-shim install (like `harbor`, the ACP entry loads the moat
+// as in-code factories rather than discovered extensions). A single stray stdout
+// line breaks the JSON-RPC stream and the host disconnects.
+else if (sub === "acp") {
+  const nodeArgs = fs.existsSync(ENV_FILE) ? [`--env-file=${ENV_FILE}`] : [];
+  runToCompletion(NODE_BIN, [...nodeArgs, path.join(REPO, "bin", "privateer-acp.mjs"), ...args.slice(1)]);
+}
+
 // --- normal launch: install the moat, then exec Pi's TUI -------------------
 else {
   // Windows has no bash out of the box, but Privateer's command tool needs one. If a

package/extensions/privateer-gate.ts

@@ -27,6 +27,7 @@ import { makeExtensionsControl } from "../src/remote/extensionsControl.ts";
 import { makeSkillsControl } from "../src/remote/skillsControl.ts";
 import { agentDir } from "../src/config/paths.ts";
 import { inHarborDaemon } from "../src/config/harborDaemon.ts";
+import { discoveredGateApplies } from "../src/config/inlineMoat.ts";
 import { agentVersion } from "../src/config/version.ts";
 import { SettingsManager } from "@earendil-works/pi-coding-agent";
 import { matchesKey } from "@earendil-works/pi-tui";
@@ -434,7 +435,22 @@ const gate = makePermissionGate({
 
 export default function privateerControl(pi: any): void {
   piRef = pi;
-  gate(pi); // tool_call (block/allow) + tool_result (redact)
+  // The moat — tool_call (block/allow) + tool_result (redact) — but ONLY when this
+  // session doesn't already carry one. A process that builds its sessions with
+  // makePermissionGate() as an inline factory (the harbor and its live task spawns,
+  // the channels runner) still auto-discovers this shim from the shared agent dir,
+  // and Pi runs EVERY tool_call handler — stopping early only on a block. Installing
+  // here too would mean two gates on one call: a second, redundant approval dialog
+  // where a UI is bound (a live task spawn), and a fail-closed local deny where one
+  // isn't (this file's bridge has no relay outside `/remote-access`). The session's
+  // own gate is the right one — it knows that session's cwd and its approver. See
+  // config/inlineMoat.ts for the full failure shape.
+  //
+  // A subagent child is the exception: it loads this file EXPLICITLY (`-e`, see
+  // bin/privateer-subagent.mjs) as its only gate, and inherits the parent's env — so
+  // it must keep installing regardless of the inherited marker, or children of a
+  // harbor task would run entirely ungated.
+  if (discoveredGateApplies(isSubagentChild())) gate(pi);
 
   // Top-level session: watch the subagent approval channel and relay each child's
   // gated action to the app over this session's bridge. The bridge fails closed while

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "privateer-agent",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "description": "Privateer — a provider-agnostic, safe-by-default terminal coding agent with TEE/Tinfoil attestation, rebuilt on the Pi toolkit. Bring your own model across 20 providers.",
   "type": "module",
   "license": "MIT",
@@ -68,6 +68,7 @@
     "@noble/curves": "^1.9.7",
     "@noble/hashes": "^1.7.1",
     "@phala/dcap-qvl": "^0.5.2",
+    "@zed-industries/agent-client-protocol": "^0.4.5",
     "patch-package": "^8.0.1",
     "pi-mcp-adapter": "^2.11.0",
     "pi-privacy": "^0.9.0",

package/src/acp/protocol.ts

@@ -0,0 +1,145 @@
+// Pure ACP <-> Privateer mappings.
+//
+// Everything here is a total function over plain data: no connection, no Pi, no
+// clock. That's what makes tests/acp.test.ts able to pin the wire contract without
+// spawning an agent or a relay — the same split that keeps `messageFromDiscord`
+// testable apart from the Discord socket.
+//
+// The shapes come from @zed-industries/agent-client-protocol (the protocol authors'
+// own package), NOT from prose docs. That distinction already mattered twice:
+// the published docs claimed `stopReason: "Completed"` and a `channel_id` tag, and
+// both were wrong. Types win; prose loses.
+
+import type { ContentBlock, PermissionOption, RequestPermissionResponse } from "@zed-industries/agent-client-protocol";
+import type { AskOutcome } from "../permissions/modeGate.ts";
+import type { PermissionRequest } from "../permissions/gate.ts";
+import { isDangerousCommand, DEFAULT_DENYLIST } from "../permissions/danger.ts";
+
+/**
+ * Flatten ACP content blocks into the single string Pi's `session.prompt` takes.
+ *
+ * We advertise only the block kinds we can faithfully represent (see
+ * PROMPT_CAPABILITIES). Anything richer that arrives anyway is rendered as a
+ * labelled placeholder rather than dropped — silently discarding part of a user's
+ * message is worse than telling the model something was attached.
+ */
+export function promptText(blocks: ContentBlock[]): string {
+  const parts: string[] = [];
+  for (const b of blocks ?? []) {
+    switch (b.type) {
+      case "text":
+        parts.push(b.text);
+        break;
+      case "resource_link":
+        // A pointer to something the agent can open with its own tools.
+        parts.push(`[resource: ${b.name ?? b.uri}](${b.uri})`);
+        break;
+      case "resource": {
+        // Embedded context — the client inlined the bytes so we need no round-trip.
+        const r: any = b.resource;
+        if (typeof r?.text === "string") {
+          parts.push(r.uri ? `<resource uri="${r.uri}">\n${r.text}\n</resource>` : r.text);
+        } else if (r?.uri) {
+          parts.push(`[resource: ${r.uri}]`);
+        }
+        break;
+      }
+      case "image":
+        parts.push(`[image attached: ${(b as any).mimeType ?? "image"}]`);
+        break;
+      case "audio":
+        parts.push(`[audio attached: ${(b as any).mimeType ?? "audio"}]`);
+        break;
+      default:
+        parts.push(`[unsupported content block: ${(b as any)?.type ?? "unknown"}]`);
+    }
+  }
+  return parts.join("\n\n").trim();
+}
+
+/**
+ * May this decision be remembered for the rest of the session?
+ *
+ * The gate has TWO destructive classes and only one of them is visible on the
+ * request. `alwaysAsk`/`protected` are fields; **dangerous shell** (`rm -rf`,
+ * `curl … | sh`, `dd of=/dev/…`, force-push to main, secret-exfil shapes) is
+ * computed inside `decideAuto` and never stamped back onto the request. Checking
+ * only the fields therefore let a dangerous command be cached, which is precisely
+ * what ModeGate refuses to do locally:
+ *
+ *   "A dangerous command … can be approved once, but is never remembered: adding
+ *    it to the allowlist or relaxing the mode would let a later variant slip
+ *    through."  — permissions/modeGate.ts
+ *
+ * On the ACP path `getRemote()` is always true, so ModeGate's remote branch returns
+ * before that check ever runs — this predicate is the only thing enforcing it. Used
+ * by BOTH the option list and the cache write so the two can't drift apart.
+ *
+ * `DEFAULT_DENYLIST` is the right default here: src/acp/run.ts sets no
+ * `ctrl.denylist`, and permissionGate.ts falls back to exactly this list.
+ */
+export function canRemember(req: PermissionRequest, denylist: string[] = DEFAULT_DENYLIST): boolean {
+  if (req.alwaysAsk || req.protected) return false;
+  if (req.kind === "bash" && isDangerousCommand(req.detail ?? "", denylist)) return false;
+  return true;
+}
+
+/**
+ * The choices we offer a human for one gated action.
+ *
+ * "always" is withheld for anything `canRemember` rejects — a destructive action, a
+ * guarded file, or a dangerous shell command must never become standing permission,
+ * which is the same rule the TUI and the relay enforce. Offering the option and then
+ * ignoring it would be worse than not offering it.
+ */
+export function permissionOptions(req: PermissionRequest): PermissionOption[] {
+  const sticky = canRemember(req);
+  const options: PermissionOption[] = [{ optionId: "allow", name: "Allow", kind: "allow_once" }];
+  if (sticky) options.push({ optionId: "always", name: "Allow for the rest of this session", kind: "allow_always" });
+  options.push({ optionId: "deny", name: "Deny", kind: "reject_once" });
+  return options;
+}
+
+/**
+ * Map the client's answer back to a gate outcome. FAIL-CLOSED: anything we don't
+ * recognize — a cancelled prompt, an option id we never offered, a malformed
+ * response — is a denial. An ambiguous answer must never widen permission.
+ */
+export function outcomeToAsk(res: RequestPermissionResponse | undefined): AskOutcome {
+  const outcome = res?.outcome;
+  if (!outcome || outcome.outcome !== "selected") return "deny";
+  switch (outcome.optionId) {
+    case "allow":
+      return "allow";
+    case "always":
+      return "always";
+    default:
+      return "deny";
+  }
+}
+
+/** A one-line human summary of a gated action, for the client's permission UI. */
+export function permissionTitle(req: PermissionRequest): string {
+  const detail = req.detail?.trim() ?? "";
+  const firstLine = detail.split("\n")[0]?.slice(0, 120) ?? "";
+  return firstLine ? `${req.title} — ${firstLine}` : req.title;
+}
+
+/** Privateer's permission kinds, in ACP's vocabulary. Exhaustive over PermissionKind
+ *  ("write" | "edit" | "bash" | "fetch" | "read"), so adding a kind is a type error
+ *  here rather than a silent "other" in someone's approval dialog. */
+export function toolKindFor(req: PermissionRequest): "read" | "edit" | "execute" | "fetch" | "other" {
+  switch (req.kind) {
+    case "read":
+      return "read";
+    case "write":
+    case "edit":
+      return "edit";
+    case "bash":
+      return "execute";
+    case "fetch":
+      return "fetch";
+    default:
+      return "other";
+  }
+}