privateer-agent 0.6.3 → 0.6.6

package/skills/resolve-dependencies/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: "resolve-dependencies"
+description: "Resolve a missing system binary/CLI tool or language package (npm/pip/cargo/go/gem) in the current environment. Use when a command fails with 'command not found', a build/test fails on a missing tool, or code fails on an unresolved import/module. Detects the right package manager, prefers a user-writable install, and runs the concrete install command through the permission gate."
+---
+
+# Resolving missing dependencies
+
+When work is blocked because a **system tool** (e.g. `ripgrep`, `jq`, `cmake`) or a
+**language package** (e.g. `zod`, `requests`, `serde`) is not installed, resolve it
+deliberately. You are running on the user's own machine — installs are real and
+persist — so pick the smallest, least-privileged command that unblocks the task and
+let the user approve it.
+
+Never install silently to "just make it work." Confirm what's missing, choose the
+narrowest install, and run it through the normal `bash` tool so the permission gate
+shows the user the exact command. Do not pipe remote scripts into a shell
+(`curl … | sh`) — the gate flags that as dangerous and it is rarely the right way to
+get a dependency.
+
+## 1. Confirm it's actually missing
+
+Before installing anything, verify the gap:
+
+- System tool: `command -v <tool>` (or `which <tool>`). Empty output → missing.
+- Language package: check the project manifest first (`package.json`,
+  `requirements.txt` / `pyproject.toml`, `Cargo.toml`, `go.mod`, `Gemfile`). If the
+  package is already declared, the fix is usually **install project deps**
+  (`npm install`, `pip install -r requirements.txt`), not adding a new one.
+
+If a tool is missing only for this one command, consider whether an already-present
+alternative works (e.g. `rg` → `grep -r`, `jq` → a small `node`/`python` one-liner)
+before installing.
+
+## 2. Detect the right package manager
+
+**Language packages** — pick from the manifest that exists in the project (do not
+guess the ecosystem):
+
+| Manifest present            | Add a package                               | Install declared deps            |
+| --------------------------- | ------------------------------------------- | -------------------------------- |
+| `package.json`              | `npm install <pkg>` (or `pnpm add`/`yarn add` if that lockfile is present) | `npm install`                    |
+| `requirements.txt`          | `pip install <pkg>`                         | `pip install -r requirements.txt`|
+| `pyproject.toml` (Poetry)   | `poetry add <pkg>`                          | `poetry install`                 |
+| `pyproject.toml` (uv)       | `uv add <pkg>`                              | `uv sync`                        |
+| `Cargo.toml`                | `cargo add <pkg>`                           | `cargo build`                    |
+| `go.mod`                    | `go get <pkg>`                              | `go mod download`                |
+| `Gemfile`                   | `bundle add <pkg>`                          | `bundle install`                 |
+
+Match the lockfile, not just the manifest: `pnpm-lock.yaml` → use `pnpm`,
+`yarn.lock` → `yarn`, `bun.lockb` → `bun`. Adding a package edits the manifest —
+that's usually wanted, but say so if the user only asked to run something.
+
+**System binaries** — detect the OS package manager by probing, in order, and use the
+first one available:
+
+| `command -v` hit | Install command                    | Notes                              |
+| ---------------- | ---------------------------------- | ---------------------------------- |
+| `brew`           | `brew install <pkg>`               | macOS/Linuxbrew — no sudo, preferred |
+| `apt-get`        | `sudo apt-get install -y <pkg>`    | Debian/Ubuntu; run `apt-get update` first if the install 404s |
+| `dnf` / `yum`    | `sudo dnf install -y <pkg>`        | Fedora/RHEL                        |
+| `apk`            | `apk add <pkg>` (`sudo` if needed) | Alpine                             |
+| `pacman`         | `sudo pacman -S --noconfirm <pkg>` | Arch                               |
+| `nix-env`        | `nix-env -iA nixpkgs.<pkg>`        | Nix — no sudo                      |
+| `zypper`         | `sudo zypper install -y <pkg>`     | openSUSE                           |
+
+The package name is not always the command name (e.g. the `fd` command ships as
+`fd-find` on apt, `fd` on brew). If unsure of the exact package name, use the
+`web_search` / `web_fetch` tools to confirm it for the detected package manager
+before running the install.
+
+## 3. Prefer the least-privileged install
+
+- Reach for a **no-sudo** manager first (`brew`, `nix`, language package managers)
+  before a system one that needs `sudo`.
+- For language packages outside a project, prefer a **user or isolated install**
+  over a global one:
+  - Python: a virtualenv (`python -m venv .venv && . .venv/bin/activate`) or
+    `pip install --user <pkg>` rather than a system-wide `sudo pip`.
+  - Node CLIs you only need to run once: `npx <pkg>` instead of `npm install -g`.
+- Only escalate to `sudo` / system-wide when there is no user-writable option and the
+  task genuinely needs it. Explain why in the same message so the user's approval is
+  informed.
+
+## 4. Run it and verify
+
+Run the chosen command via the `bash` tool (never fabricate success). The permission
+gate will surface the exact command to the user — that is intended, so keep the
+command to the single thing you need.
+
+After it completes:
+
+1. Re-check availability (`command -v <tool>`, or re-run the failing import/build).
+2. Retry the original task.
+3. If the install was denied or failed, **stop and tell the user** what's missing and
+   the command you would run — do not loop on variants of the same install.
+
+## Notes
+
+- If the environment looks locked-down (read-only filesystem, no package manager
+  found, no network), say so plainly and ask how the user wants to proceed rather than
+  hunting for a workaround.
+- One dependency at a time when debugging a broken environment — install, verify,
+  then move on — so a failure is easy to attribute.

package/src/cli/chat.ts

@@ -281,6 +281,8 @@ async function main() {
     },
     getRemote: bridge.getRemote,
     getNoQuarter: bridge.getNoQuarter,
+    // `--no-quarter` at launch (env PRIVATEER_NO_QUARTER) → total gate bypass, no prompts.
+    getSkipAllPermissions: () => process.env.PRIVATEER_NO_QUARTER === "1",
     remoteAsk: bridge.remoteAsk,
     // Subagents (and their child-only intercom tools) can't be driven from the app
     // yet — pi-subagents runs each in a child session whose gate/UI bypass the relay,

package/src/config/hosted.ts

@@ -1,3 +1,8 @@
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { globalDir } from "./paths.ts";
+import { terminalPublicKeyBase64 } from "../crypto/terminalKey.ts";
+
 // Harbor hosted mode.
 //
 // When true, this daemon is running inside Privateer's confidential-VM fleet
@@ -11,3 +16,34 @@
 export function isHosted(): boolean {
   return process.env.HARBOR_HOSTED === "1";
 }
+
+/**
+ * Publish this daemon's relay identity key so the Harbor host can attest it.
+ *
+ * ATTESTATION CONTRACT (host side: treeview `server/services/harborOrchestrator/`):
+ * the orchestrator mints the SEV-SNP report on the CVM host — configfs-tsm is a
+ * privileged kernel interface a rootless tenant deliberately cannot reach — and binds
+ * `report_data[0:32] = sha256(DER-SPKI(terminalPub))`. To do that it needs OUR public
+ * key, so we drop it in `$PRIVATEER_HOME` (bind-mounted from host tmpfs) as the mirror
+ * of the `routines/relay-id` file the host seeds for us.
+ *
+ * It must be the key the app ACTUALLY drives over the relay — the same value we send
+ * in sendContext({ terminalPub }) — otherwise the app's fail-closed check reports a
+ * key mismatch. Base64 of the raw 32 X25519 bytes; the host wraps it in the SPKI DER
+ * prefix itself. Minting happens on first call, which is fine: this runs at boot,
+ * before the relay registers.
+ *
+ * Hosted-only and best-effort: on a user's own machine this is a no-op, and a write
+ * failure must never take the daemon down — attestation simply fail-closes host-side
+ * with HARBOR_ATTEST_NO_KEY rather than reporting a false "attested".
+ */
+export function publishRelayPub(): void {
+  if (!isHosted()) return;
+  try {
+    writeFileSync(join(globalDir(), "relay-pub"), terminalPublicKeyBase64(), { mode: 0o600 });
+  } catch (err) {
+    console.error(
+      `[harbor] could not publish relay-pub — enclave attestation will fail closed: ${String(err)}`,
+    );
+  }
+}

package/src/daemon/index.ts

@@ -20,6 +20,7 @@ import { RelayClient, type TaskSpec } from "../remote/relayClient.ts";
 import { createLiveTaskSession, type LiveTaskHandle } from "../remote/liveTaskSession.ts";
 import { makeRoutinesControl } from "../remote/routinesControl.ts";
 import { makeChannelsControl } from "../remote/channelsControl.ts";
+import { makeMcpControl } from "../remote/mcpControl.ts";
 import { makeWorkflowsControl } from "../remote/workflowsControl.ts";
 import { runWorkflow as executeWorkflow, type RunnerDeps, type AgentRunSpec, type AgentRunResult, type ScriptRunResult } from "../workflows/runner.ts";
 import type { Workflow, Step } from "../workflows/schema.ts";
@@ -50,7 +51,7 @@ import { deliver, type RelayPusher, type CloudPusher } from "../routines/deliver
 import { sealJson, decodeAccountPublicKey } from "../crypto/outboxSeal.ts";
 import { redactText, collectSecrets } from "../util/redact.ts";
 import { startIpcServer, type IpcRequest, type IpcResponse } from "./ipc.ts";
-import { isHosted } from "../config/hosted.ts";
+import { isHosted, publishRelayPub } from "../config/hosted.ts";
 
 // The safe, read-only toolset for unattended runs — Pi builtins with no
 // write/edit/bash, so a routine firing with nobody watching can't mutate the
@@ -190,6 +191,13 @@ export class Daemon {
     runningPlatforms: () => readRunningPlatforms(),
   });
 
+  // App-facing MCP connector management (list/save/set_enabled/remove) over the
+  // daemon's relay — the daemon is the Node HOST that actually runs the adapter (a
+  // phone/web client can't). Edits the SHARED agent/mcp-desktop.json + mcp.json, so a
+  // machine has one MCP config whether it was set from the desktop (IPC) or the phone
+  // (relay). Tokens ride in a SEALED box (applyMcpSave) — the relay never sees them.
+  private readonly mcp = makeMcpControl();
+
   // App-facing workflow management (list/get/save/remove/run) over the daemon's relay.
   // Run-now is injected here since only the daemon owns the runner + its seams. A
   // workflow can carry a `script` step (RCE if forged), so every mutation is
@@ -219,6 +227,9 @@ export class Daemon {
   };
 
   start(): void {
+    // Hosted only: publish our relay pubkey for the host to bind into the SEV-SNP
+    // report. Before syncRelay() so the key exists by the time we're reachable.
+    publishRelayPub();
     this.primeSchedule();
     this.timer = setInterval(() => void this.tick(), TICK_MS);
     this.server = startIpcServer((req) => this.handleIpc(req));
@@ -287,6 +298,14 @@ export class Daemon {
         onChannelsList: () => this.pushChannels(),
         onChannelsSave: (draft, sealedSecrets, sig, ts) => this.pushChannels(this.applyChannelSave(draft, sealedSecrets, sig, ts)),
         onChannelsRemove: (platform, sig, ts) => this.pushChannels(this.guardControl("channels_remove", { platform }, sig, ts, () => this.channels.remove(platform as any).message)),
+        // MCP connector management from the app. `save` has its own signed verify (it
+        // carries a sealed env box — applyMcpSave); `set_enabled`/`remove` are
+        // account-signed here (H2 — a forged toggle arms/disarms a tool surface; a
+        // forged removal is a DoS). Then mcpControl writes the shared config + re-pushes.
+        onMcpList: () => this.pushMcp(),
+        onMcpSave: (draft, sealedSecrets, sig, ts) => this.pushMcp(this.applyMcpSave(draft, sealedSecrets, sig, ts)),
+        onMcpSetEnabled: (name, enabled, sig, ts) => this.pushMcp(this.guardControl("mcp_set_enabled", { name, enabled }, sig, ts, () => this.mcp.setEnabled(name, enabled).message)),
+        onMcpRemove: (name, sig, ts) => this.pushMcp(this.guardControl("mcp_remove", { name }, sig, ts, () => this.mcp.remove(name).message)),
         // Workflow management from the app. Each MUTATION is account-signed (H2) — a forged
         // workflows_save plants a `script` step that bypasses the permission gate (RCE),
         // and workflows_run executes the graph — so all three are verified (guardControl,
@@ -340,6 +359,42 @@ export class Daemon {
     this.relay?.sendChannels({ items: this.channels.list(), message });
   }
 
+  private pushMcp(message?: string): void {
+    this.relay?.sendMcp({ items: this.mcp.list(), message });
+  }
+
+  // Verify an account-signed MCP save (H2) that also carries a SEALED env box, then
+  // apply it. Same shape as applyChannelSave but routed through the generic signed
+  // envelope (action "mcp_save", args {draft, sealedSecrets}) — the action tag stops a
+  // signature made for any other frame from being replayed as an MCP save. Fail-closed:
+  // an unsigned/forged/stale frame returns the refusal message and NOTHING is written.
+  // The sealed box opens to { termId, env } — a token the relay never sees in the clear.
+  private applyMcpSave(draft: Record<string, unknown>, sealedSecrets?: string, sig?: string, ts?: number): string | undefined {
+    const auth = authorizeControl(
+      routineRelayId(),
+      "mcp_save",
+      { draft, sealedSecrets: sealedSecrets ?? null },
+      sig,
+      ts,
+    );
+    if (!auth.ok) return auth.message;
+
+    let withEnv = draft;
+    if (sealedSecrets) {
+      let opened: { termId?: string; env?: Record<string, string> };
+      try {
+        opened = openJsonFromApp(sealedSecrets);
+      } catch {
+        return "Couldn't decrypt the connector credentials — they may have been sealed to a different terminal.";
+      }
+      if (opened.termId !== routineRelayId()) {
+        return "These credentials were addressed to a different terminal.";
+      }
+      withEnv = { ...draft, env: opened.env ?? {} };
+    }
+    return this.mcp.save(withEnv as any).message;
+  }
+
   // Push the current workflow summaries to an attached controller (its workflows
   // manager). `message` is a one-line result from the last mutation, if any.
   private pushWorkflows(message?: string): void {
@@ -600,9 +655,14 @@ export class Daemon {
     const config = loadDaemonConfig();
     const modelSpec = routine.model ?? config.defaultModel;
     const split = splitRoutineTools(routine.tools);
-    const allowedTools = split.builtin.length > 0 ? split.builtin : SAFE_TOOLS;
-    if (split.mcp.length > 0 || routine.delivery.includes("email")) {
-      log("  note: MCP tools + email delivery are not wired yet (Phase 5) — skipping those");
+    // MCP tools (server__tool) join the allow-list: the mcpAdapter loaded in runSession
+    // registers them from the shared mcp.json, and the routine's SIGNED tool list is the
+    // authorization boundary under the bypass gate (same as builtin tools). An http/OAuth
+    // connector that never completed its browser flow simply errors at call time.
+    const builtinAllow = split.builtin.length > 0 ? split.builtin : SAFE_TOOLS;
+    const allowedTools = [...builtinAllow, ...split.mcp];
+    if (routine.delivery.includes("email")) {
+      log("  note: email delivery is not wired yet (Phase 5) — skipping it");
     }
 
     const { out, status, error } = await this.runSession({
@@ -655,11 +715,19 @@ export class Daemon {
           return "deny";
         },
       };
+      // MCP adapter (Phase 5): registers the tools from the shared agent/mcp.json — the
+      // same projection the app's MCP manager (mcpControl) writes over the relay. No
+      // servers configured → a no-op. Dynamically imported so it loads only when a
+      // session actually runs (Pi is already booted by here). The specifier is a
+      // variable so tsc treats it as Promise<any> and doesn't pull the third-party
+      // adapter's own .ts into our typecheck — same intent as the desktop's agentImport.
+      const mcpAdapterSpec = "pi-mcp-adapter";
+      const { default: mcpAdapter } = await import(mcpAdapterSpec);
       const services = await createAgentSessionServices({
         cwd: spec.cwd,
         agentDir: agentDir(),
         resourceLoaderOptions: {
-          extensionFactories: [makePermissionGate(gate), makePiPrivacyExtension(), makeAccountProvider()] as any,
+          extensionFactories: [makePermissionGate(gate), makePiPrivacyExtension(), makeAccountProvider(), mcpAdapter] as any,
         },
       });
       servicesRef = services as any;
@@ -724,7 +792,7 @@ export class Daemon {
     const cwd = spec.cwd && spec.cwd.trim() ? spec.cwd : process.cwd();
     const modelSpec = spec.model && spec.model.trim() ? spec.model : config.defaultModel;
     const split = spec.tools && spec.tools.length ? splitRoutineTools(spec.tools) : undefined;
-    const allowedTools = split && split.builtin.length > 0 ? split.builtin : SAFE_TOOLS;
+    const allowedTools = [...(split && split.builtin.length > 0 ? split.builtin : SAFE_TOOLS), ...(split?.mcp ?? [])];
     const title = deriveTaskTitle(spec);
     const key = `task:${title}`;
     if (this.running.has(key)) {
@@ -904,7 +972,7 @@ export class Daemon {
     const config = loadDaemonConfig();
     const model = spec.model && spec.model.trim() ? spec.model : config.defaultModel;
     const split = spec.tools && spec.tools.length ? splitRoutineTools(spec.tools) : undefined;
-    const tools = split && split.builtin.length > 0 ? split.builtin : SAFE_TOOLS;
+    const tools = [...(split && split.builtin.length > 0 ? split.builtin : SAFE_TOOLS), ...(split?.mcp ?? [])];
     const { out, status, error } = await this.runSession({ prompt: spec.prompt, cwd: spec.cwd, model, tools });
     let output: Record<string, unknown> = {};
     try { const p = JSON.parse(out.trim()); if (p && typeof p === "object" && !Array.isArray(p)) output = p as Record<string, unknown>; } catch { /* non-JSON → raw text only */ }

package/src/ext/permissionGate.ts

@@ -44,6 +44,10 @@ export interface GateController {
   confineToCwd?: boolean;
   getRemote?(): boolean;
   getNoQuarter?(): boolean;
+  // Total bypass — see ModeGate.getSkipAllPermissions. Set by the `--no-quarter`
+  // launch flag (env PRIVATEER_NO_QUARTER); when true the gate auto-allows every
+  // action with no prompt.
+  getSkipAllPermissions?(): boolean;
   // Block a tool outright while the turn is remote-driven (only consulted when
   // getRemote() is true). For tools whose own prompts render on the host terminal
   // rather than the relay — e.g. pi-subagents — so a driven turn can't wedge on an
@@ -132,20 +136,26 @@ export async function decideToolCall(
     ask,
     getRemote: ctrl.getRemote,
     getNoQuarter: ctrl.getNoQuarter,
+    getSkipAllPermissions: ctrl.getSkipAllPermissions,
   });
 
   let decision: "allow" | "deny";
   try {
     decision = await withTimeout(gate.request(req), ctrl.approvalTimeoutMs, ctx.signal);
   } catch (err) {
-    // Fail closed: a thrown/aborted/timed-out approval blocks the tool.
+    // Fail closed: a thrown/aborted/timed-out approval blocks the tool. Phrase it
+    // as terminal — re-issuing the identical call will hit the same closed gate, so
+    // tell the model to stop retrying and take a different path (or ask the user).
     return {
       block: true,
-      reason: `Approval unavailable (${(err as Error)?.message ?? "error"}) — blocked by default`,
+      reason: `Approval unavailable (${(err as Error)?.message ?? "error"}) — blocked by default. Do not retry the same command; it will be blocked again. Try a different approach or ask the user to run it.`,
     };
   }
   if (decision === "deny") {
-    return { block: true, reason: `${req.title} denied by permission gate` };
+    return {
+      block: true,
+      reason: `${req.title} was denied by the permission gate. Do not retry the same command; it will be denied again. Take a different approach or ask the user to run it themselves.`,
+    };
   }
   return undefined;
 }

package/src/permissions/modeGate.ts

@@ -34,6 +34,13 @@ export interface ModeGateDeps {
   // pinging the phone. Dangerous shell and alwaysAsk-destructive actions rank
   // above bypass in decideAuto, so those still relay for an explicit Allow/Deny.
   getNoQuarter?: () => boolean;
+  // True when the operator launched with `--no-quarter` (env PRIVATEER_NO_QUARTER):
+  // a session-wide TOTAL bypass of the gate. Every request auto-approves — including
+  // dangerous shell, destructive tools, out-of-cwd and protected-file access — with
+  // no prompt, local or remote. This sits ABOVE everything else (mode, allowlist,
+  // the remote branch, even the dangerous-command denylist): the operator has
+  // explicitly opted the whole session out of the moat. Off unless the flag is set.
+  getSkipAllPermissions?: () => boolean;
 }
 
 // The permission gate used by the live TUI. It first applies the mode/allowlist
@@ -43,6 +50,13 @@ export class ModeGate implements PermissionGate {
   constructor(private readonly deps: ModeGateDeps) {}
 
   async request(req: PermissionRequest): Promise<PermissionDecision> {
+    // No-quarter: the operator launched with `--no-quarter`, opting the whole
+    // session out of the gate. Total bypass — auto-allow EVERY request (dangerous
+    // shell, destructive tools, outside-cwd, protected files) with no prompt, before
+    // any mode/allowlist/remote/denylist policy is consulted. Deliberately the very
+    // first check so nothing below can force an "ask" back on.
+    if (this.deps.getSkipAllPermissions?.()) return "allow";
+
     const denylist = this.deps.denylist ?? [];
     const auto = decideAuto(req, this.deps.getMode(), this.deps.allowlist, denylist);
 

package/src/remote/mcpControl.ts

@@ -0,0 +1,268 @@
+/**
+ * MCP connector management for the app — the sibling of channelsControl.ts, but for
+ * MCP server config rather than messaging channels. It is what lets the phone/web
+ * client add, toggle, and remove MCP connectors on a Node HOST it drives over the
+ * relay (the daemon 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
+ * 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
+ * means a machine has ONE coherent MCP config whether it was edited from the desktop
+ * over IPC or from the phone over the relay.
+ *
+ * SECRETS: MCP env values are credentials (GITHUB_PERSONAL_ACCESS_TOKEN, …). Over the
+ * untrusted relay they are WRITE-ONLY, exactly like channel bot tokens: list() NEVER
+ * returns an env VALUE — only which env keys exist (`envKeys`) and which are non-empty
+ * (`secretsSet`), by name. save() persists whatever env VALUES it is handed in
+ * `draft.env`; the seal/open of those values in transit is the caller's job (the
+ * daemon opens a sealed-box addressed to its terminal, mirroring applyChannelSave), so
+ * this module only ever deals in the plaintext files it already owns.
+ *
+ * Framework-agnostic: nothing here imports React or the relay. The caller owns the
+ * frame plumbing and the sealed-secret open.
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { agentDir } from "../config/paths.ts";
+
+export type McpTransport = "stdio" | "http";
+
+// 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 {
+  transport?: McpTransport;
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  url?: string;
+  oauth?: boolean;
+  enabled?: boolean;
+}
+interface SourceFile {
+  servers: Record<string, SourceEntry>;
+}
+
+// Non-secret projection of one server, sent to the app. No env VALUES, ever — only
+// which env keys exist and which are set (`secretsSet`). `host` is surfaced for the
+// app's privacy badge ("Sends data to <host>" for http; stdio runs locally).
+export interface RemoteMcpServer {
+  name: string;
+  transport: McpTransport;
+  enabled: boolean;
+  command?: string; // stdio: the launch binary (not a secret — e.g. "npx")
+  argsPreview?: string; // stdio: args joined, for a one-line summary
+  url?: string; // http: the endpoint (not a secret; the vendor host)
+  host?: string; // http: parsed host for the privacy badge
+  oauth: boolean; // http servers negotiate OAuth; stdio never does
+  envKeys: string[]; // env var NAMES only (e.g. ["GITHUB_PERSONAL_ACCESS_TOKEN"])
+  secretsSet: string[]; // subset of envKeys whose value is non-empty — names only
+}
+
+// An app-submitted edit. Non-secret fields REPLACE when present; `env` maps a var
+// name → its (already-opened) value, and only present, non-empty values overwrite —
+// an omitted key keeps the existing value (so a re-save without re-typing the token
+// preserves it, matching the channels-manager rule).
+export interface McpDraft {
+  name: string;
+  transport?: McpTransport;
+  command?: string;
+  args?: string[];
+  url?: string;
+  oauth?: boolean;
+  env?: Record<string, string>;
+}
+
+export interface McpControl {
+  // Every managed server, non-secret projection. Enabled or not — the app shows
+  // disabled connectors so they can be toggled back on.
+  list(): RemoteMcpServer[];
+  // Create or edit a server. Validates transport ⟷ required field (stdio→command,
+  // http→url). Returns a one-line result. Re-projects mcp.json on success.
+  save(draft: McpDraft): { ok: boolean; message?: string };
+  // Enable/disable a server (re-projects). ok:false when the name is unknown.
+  setEnabled(name: string, enabled: boolean): { ok: boolean; message?: string };
+  // Delete a server entirely (re-projects). ok:false when nothing was configured.
+  remove(name: string): { ok: boolean; message?: string };
+}
+
+const TRANSPORTS: readonly McpTransport[] = ["stdio", "http"];
+function isTransport(v: unknown): v is McpTransport {
+  return typeof v === "string" && TRANSPORTS.includes(v as McpTransport);
+}
+
+function hostOf(url: string): string | undefined {
+  try {
+    return new URL(url).host || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function cleanArgs(v: unknown): string[] | undefined {
+  if (!Array.isArray(v)) return undefined;
+  return v.map((x) => String(x ?? "")).filter((s) => s.length > 0);
+}
+
+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.
+  dir?: () => string;
+}): McpControl {
+  const dir = opts?.dir ?? agentDir;
+  const sourcePath = () => join(dir(), "mcp-desktop.json");
+  const projectionPath = () => join(dir(), "mcp.json");
+
+  function readSource(): SourceFile {
+    // Seed from an existing standard mcp.json on first run (a machine that already
+    // had connectors before this control existed), so nothing is silently dropped.
+    try {
+      const raw = JSON.parse(readFileSync(sourcePath(), "utf8"));
+      if (raw && typeof raw === "object" && raw.servers) return { servers: raw.servers };
+    } catch {
+      /* fall through to seed */
+    }
+    const servers: Record<string, SourceEntry> = {};
+    try {
+      const proj = JSON.parse(readFileSync(projectionPath(), "utf8"));
+      for (const [name, entry] of Object.entries(proj?.mcpServers ?? {})) {
+        servers[name] = { ...(entry as SourceEntry), enabled: true };
+      }
+    } catch {
+      /* no prior config */
+    }
+    return { servers };
+  }
+
+  function writeSource(src: SourceFile): void {
+    mkdirSync(dirname(sourcePath()), { recursive: true });
+    writeFileSync(sourcePath(), JSON.stringify(src, null, 2) + "\n");
+    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.
+  function project(src: SourceFile): void {
+    const mcpServers: Record<string, unknown> = {};
+    for (const [name, e] of Object.entries(src.servers)) {
+      if (e.enabled === false) continue;
+      const { enabled, ...std } = e;
+      mcpServers[name] = std;
+    }
+    mkdirSync(dirname(projectionPath()), { recursive: true });
+    writeFileSync(projectionPath(), JSON.stringify({ mcpServers }, null, 2) + "\n");
+  }
+
+  function toRemote(name: string, e: SourceEntry): RemoteMcpServer {
+    const transport: McpTransport = e.transport ?? (e.url ? "http" : "stdio");
+    const env = e.env ?? {};
+    const envKeys = Object.keys(env);
+    return {
+      name,
+      transport,
+      enabled: e.enabled !== false,
+      command: transport === "stdio" ? e.command : undefined,
+      argsPreview: transport === "stdio" && e.args?.length ? e.args.join(" ") : undefined,
+      url: transport === "http" ? e.url : undefined,
+      host: transport === "http" && e.url ? hostOf(e.url) : undefined,
+      // http servers negotiate OAuth; stdio never does (matches mcpService.list()).
+      oauth: transport === "http",
+      envKeys,
+      secretsSet: envKeys.filter((k) => String(env[k] ?? "").length > 0),
+    };
+  }
+
+  return {
+    list(): RemoteMcpServer[] {
+      const src = readSource();
+      return Object.entries(src.servers).map(([name, e]) => toRemote(name, e));
+    },
+
+    save(draft: McpDraft): { ok: boolean; message?: string } {
+      const name = String(draft?.name ?? "").trim();
+      if (!name) return { ok: false, message: "A connector needs a name." };
+      if (draft.transport !== undefined && !isTransport(draft.transport))
+        return { ok: false, message: "Unknown transport." };
+
+      const src = readSource();
+      const prev: SourceEntry = src.servers[name] ?? {};
+      const entry: SourceEntry = { ...prev };
+
+      const transport: McpTransport =
+        (draft.transport as McpTransport) ?? prev.transport ?? (draft.url || prev.url ? "http" : "stdio");
+      entry.transport = transport;
+
+      if (transport === "stdio") {
+        if (draft.command !== undefined) entry.command = String(draft.command).trim();
+        const args = cleanArgs(draft.args);
+        if (args !== undefined) entry.args = args;
+        // A stdio server can't reach a url and never does OAuth — clear stale fields.
+        delete entry.url;
+        delete entry.oauth;
+        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();
+        if (draft.oauth !== undefined) entry.oauth = !!draft.oauth;
+        delete entry.command;
+        delete entry.args;
+        if (!entry.url) return { ok: false, message: "A remote (http) connector needs a URL." };
+      }
+
+      // Env/secrets: a present, non-empty value overwrites; an omitted key keeps the
+      // existing value (re-save without re-typing the token preserves it). An explicit
+      // empty string clears that key.
+      if (draft.env !== undefined) {
+        const merged: Record<string, string> = { ...(prev.env ?? {}) };
+        for (const [k, v] of Object.entries(draft.env)) {
+          const key = String(k).trim();
+          if (!key) continue;
+          const val = String(v ?? "");
+          if (val.length > 0) merged[key] = val;
+          else delete merged[key];
+        }
+        if (Object.keys(merged).length > 0) entry.env = merged;
+        else delete entry.env;
+      }
+
+      // A brand-new server comes up enabled; an edit preserves the prior flag.
+      entry.enabled = prev.enabled ?? true;
+
+      src.servers[name] = entry;
+      try {
+        writeSource(src);
+      } catch (e) {
+        return { ok: false, message: `Couldn't write MCP config: ${e instanceof Error ? e.message : String(e)}` };
+      }
+      return { ok: true, message: `Saved "${name}".` };
+    },
+
+    setEnabled(name: string, enabled: boolean): { ok: boolean; message?: string } {
+      const src = readSource();
+      if (!src.servers[name]) return { ok: false, message: "No such connector." };
+      src.servers[name].enabled = !!enabled;
+      try {
+        writeSource(src);
+      } catch (e) {
+        return { ok: false, message: `Couldn't write MCP config: ${e instanceof Error ? e.message : String(e)}` };
+      }
+      return { ok: true, message: `${enabled ? "Enabled" : "Disabled"} "${name}".` };
+    },
+
+    remove(name: string): { ok: boolean; message?: string } {
+      const src = readSource();
+      if (!src.servers[name]) return { ok: false, message: "Not configured." };
+      delete src.servers[name];
+      try {
+        writeSource(src);
+      } catch (e) {
+        return { ok: false, message: `Couldn't write MCP config: ${e instanceof Error ? e.message : String(e)}` };
+      }
+      return { ok: true, message: `Removed "${name}".` };
+    },
+  };
+}