@piagent/platform 1.1.9 → 1.2.0

package/packages/piagent-core/extensions/piagent-guard.ts

@@ -1,4 +1,5 @@
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import crypto from "node:crypto";
 import { execFileSync } from "node:child_process";
@@ -41,6 +42,10 @@ import {
 } from "./redaction-core.js";
 import { detectProfileName } from "./project-shape.js";
 import { evaluateUpdateCheck, isInstalledPlatform, readUpdateCache, startUpdateProbe } from "./update-check.js";
+import { REPOSITORY_SCOPES, collectServers } from "../mcp/mcp-config-layers.js";
+import { approvalState } from "../mcp/mcp-approval-store.js";
+import { evaluateServerReadiness, readinessNotice } from "../mcp/mcp-auth-readiness.js";
+import * as mcpActions from "../mcp/mcp-command-actions.js";
 import { buildExtendingProfile, resolveProjectProfileDocument } from "../capabilities/project-profile.js";
 import {
   resolveCapabilityProfileDocument,
@@ -441,6 +446,22 @@ function updateAvailabilityNotice(): string | undefined {
   return decision.notice;
 }
 
+// What the operator would otherwise find out when a call fails: a server that is
+// configured but cannot answer. Computed from files and environment variables
+// this process already has, with no network and no child process, because it runs
+// on every session start.
+function mcpReadinessNotice(cwd: string): string | undefined {
+  if (process.env.PIAGENT_NO_MCP_NOTICE?.trim()) return undefined;
+  try {
+    const servers = collectServers({ projectPath: cwd });
+    if (servers.length === 0) return undefined;
+    return readinessNotice(servers.map((server) => evaluateServerReadiness(server, { projectPath: cwd })));
+  } catch {
+    // Reporting on MCP is not worth failing a session start over.
+    return undefined;
+  }
+}
+
 function loadPolicy(extensionDir: string): BasePolicy {
   const root = findPackageRoot(extensionDir);
   return readJsonFile<BasePolicy>(path.join(root, "policies", "base-policy.json")) ?? DEFAULT_POLICY;
@@ -1972,6 +1993,82 @@ function prepareToolInputForPolicy(
   };
 }
 
+// Which MCP server a tool call is addressed to. The adapter exposes one proxy
+// tool named `mcp` that carries the server in `input.server`, and, when a server
+// runs with directTools, individual tools named `mcp__<server>__<tool>`. Both
+// forms are read, because a gate that only covers the proxy is bypassed by
+// turning directTools on.
+function mcpServerFromToolCall(toolName: string, input: Record<string, unknown>): string | undefined {
+  if (normalizeActionToken(toolName) === "mcp") {
+    return typeof input.server === "string" && input.server.trim() ? input.server.trim() : undefined;
+  }
+  const direct = toolName.match(/^mcp(?:__|[-_:]+)([^_:.-]+)/i);
+  return direct?.[1];
+}
+
+// Servers a repository defines are not usable until somebody on this machine has
+// approved them. This is the enforcement point: the adapter owns the connection
+// and this extension cannot prevent one being opened, but no tool call reaches an
+// unapproved server. The residual exposure is the connection itself, which is
+// worth stating plainly rather than describing this as a full block.
+//
+// Recomputed only when one of the files behind the decision changes, because
+// this runs on every tool call.
+const mcpApprovalCache = new Map<string, { signature: string; blocked: Map<string, string> }>();
+
+function unapprovedMcpServers(cwd: string): Map<string, string> {
+  const servers = collectServers({ projectPath: cwd, scopes: [...REPOSITORY_SCOPES] });
+  const signature = [
+    ...servers.map((server) => `${server.scope}:${server.name}:${fileSignature(server.file)}`),
+    `store:${fileSignature(path.join(os.homedir(), ".pi", "piagent-mcp-approvals.json"))}`
+  ].join("|");
+  const cached = mcpApprovalCache.get(cwd);
+  if (cached?.signature === signature) return cached.blocked;
+
+  const blocked = new Map<string, string>();
+  for (const server of servers) {
+    const state = approvalState({ projectPath: cwd, name: server.name, entry: server.entry });
+    if (state.state === "approved") continue;
+    blocked.set(server.name, state.state);
+  }
+  mcpApprovalCache.set(cwd, { signature, blocked });
+  return blocked;
+}
+
+function fileSignature(file: string): string {
+  try {
+    const stat = fs.statSync(file);
+    return `${stat.mtimeMs}:${stat.size}`;
+  } catch {
+    return "absent";
+  }
+}
+
+function evaluateMcpApproval(
+  cwd: string,
+  toolName: string,
+  input: Record<string, unknown>
+): { block: boolean; reason?: string } {
+  const server = mcpServerFromToolCall(toolName, input);
+  if (!server) return { block: false };
+  const state = unapprovedMcpServers(cwd).get(server);
+  if (!state) return { block: false };
+  const explanation = state === "rejected"
+    ? "it was rejected for this project"
+    : state === "changed"
+      ? "its definition changed since it was approved"
+      : "this repository defines it and nobody on this machine has approved it";
+  return {
+    block: true,
+    // Named as commands, because this is read inside a session: the reader can
+    // run these where they already are, without shelling out.
+    reason:
+      `Blocked MCP server ${server}: ${explanation}. ` +
+      `Review it with \`/piagent-mcp get ${server}\`, then \`/piagent-mcp approve ${server}\` to allow it ` +
+      `or \`/piagent-mcp reject ${server}\` to refuse it.`
+  };
+}
+
 function evaluateMcpProxyShellProtectedAccess(
   cwd: string,
   prepared: PreparedToolInput,
@@ -3751,6 +3848,10 @@ export default function piagentGuard(pi: ExtensionAPI) {
     if (permissionProfile.mode === "trusted-full-access") {
       ctx.ui.notify("Piagent permission profile trusted-full-access is active; protected paths, secret redaction, and destructive/external confirmations remain enforced.", "warning");
     }
+    // A server this repository defines and nobody approved is a decision waiting
+    // on the operator, so it is a warning and it comes before the release news.
+    const mcpNotice = mcpReadinessNotice(ctx.cwd);
+    if (mcpNotice) ctx.ui.notify(mcpNotice, "warning");
     // Last, so a release announcement never pushes a security warning out of
     // the first thing the operator reads.
     const updateNotice = updateAvailabilityNotice();
@@ -3910,6 +4011,13 @@ export default function piagentGuard(pi: ExtensionAPI) {
       return { block: true, reason: `Blocked ${event.toolName}: ${preparedInput.reason}.` };
     }
 
+    // Before anything is asked of an MCP server, whether this machine agreed to
+    // that server at all.
+    const approvalDecision = evaluateMcpApproval(ctx.cwd, event.toolName, toolInput);
+    if (approvalDecision.block) {
+      return { block: true, reason: approvalDecision.reason };
+    }
+
     if (SHELL_TOOL_NAMES.has(event.toolName)) {
       const shellInput = extractShellCommandInput(toolInput);
       if (!shellInput.command) {
@@ -5720,6 +5828,214 @@ export default function piagentGuard(pi: ExtensionAPI) {
     }
   });
 
+  /**
+   * MCP management as a command, not as a request to the model.
+   *
+   * Everything here is also reachable from the `piagent-mcp` terminal CLI. The
+   * difference is where you are standing: inside a session, typing the shell
+   * command means asking the model to run bash, read the output and tell you
+   * what it said — three model turns to answer a question this process can
+   * answer from files it has already read. So the same reports are bound to a
+   * command, which pi dispatches without involving the model at all.
+   *
+   * Bare `/piagent-mcp` opens a menu built from what this project actually has,
+   * because the surface only helps if you can find it without already knowing
+   * the subcommand you want. Every entry in that menu is also typeable, so the
+   * menu teaches the direct form rather than replacing it.
+   */
+  function registerMcpCommand(): void {
+    const ACTIONS = new Set([...mcpActions.READ_ACTIONS, ...mcpActions.SERVER_ACTIONS]);
+
+    /** Report without a model turn: the text is shown, nothing is asked. */
+    function emit(customType: string, report: { notify: { message: string; level: string }, lines: string[], details: Record<string, unknown> }, ctx: ExtensionContext): void {
+      ctx.ui.notify(report.notify.message, report.notify.level as "info" | "warning" | "error");
+      pi.sendMessage(
+        { customType, content: report.lines.join("\n"), display: true, details: report.details },
+        { triggerTurn: false }
+      );
+    }
+
+    function fail(ctx: ExtensionContext, message: string): void {
+      ctx.ui.notify(`piagent-mcp: ${message}`, "error");
+      pi.sendMessage(
+        { customType: "piagent-mcp-error", content: message, display: true, details: { error: message } },
+        { triggerTurn: false }
+      );
+    }
+
+    /**
+     * Approval decisions live outside the repository, so writing one changes no
+     * config file the gate's cache is keyed on. Drop the entry so the next tool
+     * call re-reads the decision instead of the one it replaced.
+     */
+    function forgetApprovalCache(cwd: string): void {
+      mcpApprovalCache.delete(cwd);
+    }
+
+    /** Runs one action and shows it. Both the menu and a typed subcommand land here. */
+    function runAction(ctx: ExtensionContext, action: string, name: string | undefined, scope: string | undefined): void {
+      const project = ctx.cwd;
+      switch (action) {
+        case "status":
+          emit("piagent-mcp-status", mcpActions.status({ projectPath: project, scope }), ctx);
+          return;
+        case "get":
+          emit("piagent-mcp-detail", mcpActions.detail({ projectPath: project, name: name as string, scope }), ctx);
+          return;
+        case "doctor":
+          emit("piagent-mcp-doctor", mcpActions.doctor({ projectPath: project }), ctx);
+          return;
+        case "approve":
+        case "reject": {
+          const report = mcpActions.decide({
+            projectPath: project,
+            name: name as string,
+            decision: action === "approve" ? "approved" : "rejected"
+          });
+          forgetApprovalCache(project);
+          emit("piagent-mcp-decision", report, ctx);
+          return;
+        }
+        case "reset": {
+          const report = mcpActions.reset({ projectPath: project, name });
+          forgetApprovalCache(project);
+          emit("piagent-mcp-decision", report, ctx);
+          return;
+        }
+        case "enable":
+        case "disable":
+          emit("piagent-mcp-toggle", mcpActions.toggle({
+            projectPath: project,
+            name: name as string,
+            scope,
+            enabled: action === "enable"
+          }), ctx);
+          return;
+        default:
+          fail(ctx, `unknown subcommand: ${action}. Run /piagent-mcp help.`);
+      }
+    }
+
+    /**
+     * The menu. Falls back to the plain status report when there is no select UI
+     * — print mode and JSON mode have no way to answer a prompt, and blocking
+     * there would hang a non-interactive run.
+     */
+    async function runMenu(ctx: ExtensionContext): Promise<void> {
+      const menu = mcpActions.menuOptions({ projectPath: ctx.cwd });
+      const chosen = ctx.hasUI === false
+        ? undefined
+        : await selectValueFromUi(ctx, "MCP", menu.entries, menu.entries.find((entry) => entry.recommended)?.value);
+      if (!chosen) {
+        emit("piagent-mcp-status", mcpActions.status({ projectPath: ctx.cwd }), ctx);
+        pi.sendMessage(
+          { customType: "piagent-mcp-help", content: mcpActions.HELP_LINES.join("\n"), display: true, details: {} },
+          { triggerTurn: false }
+        );
+        return;
+      }
+      if (chosen === "help") {
+        emit("piagent-mcp-help", mcpActions.help(), ctx);
+        return;
+      }
+      const terminal = mcpActions.terminalOnly(chosen);
+      if (terminal) {
+        emit("piagent-mcp-terminal", terminal, ctx);
+        return;
+      }
+      if (!mcpActions.SERVER_ACTIONS.has(chosen) || chosen === "reset") {
+        // `reset` without a name forgets everything, which is a bigger answer
+        // than the menu asked for, so it still picks a server here.
+        if (chosen !== "reset") {
+          runAction(ctx, chosen, undefined, undefined);
+          return;
+        }
+      }
+      const choices = mcpActions.serverChoices({ projectPath: ctx.cwd, action: chosen });
+      if (choices.length === 0) {
+        fail(ctx, `no server here can be ${chosen === "get" ? "inspected" : `${chosen}d`}.`);
+        return;
+      }
+      const server = choices.length === 1
+        ? choices[0].value
+        : await selectValueFromUi(ctx, `Which server to ${chosen}?`, choices);
+      if (!server) {
+        fail(ctx, `no server chosen. Run \`/piagent-mcp ${chosen} <name>\` directly.`);
+        return;
+      }
+      runAction(ctx, chosen, server, undefined);
+    }
+
+    pi.registerCommand("piagent-mcp", {
+      description: "Show and manage MCP servers, scopes and approvals without a model follow-up",
+      getArgumentCompletions: (prefix: string) => {
+        const typed = String(prefix ?? "");
+        const parts = typed.split(/\s+/);
+        if (parts.length <= 1) {
+          const items = [...ACTIONS, "help"]
+            .filter((name) => name.startsWith(parts[0] ?? ""))
+            .map((name) => ({ value: name, label: name }));
+          return items.length > 0 ? items : null;
+        }
+        if (!mcpActions.SERVER_ACTIONS.has(parts[0])) return null;
+        let names: string[] = [];
+        try {
+          names = collectServers({ projectPath: process.cwd() }).map((server) => server.name);
+        } catch {
+          return null;
+        }
+        const seen = [...new Set(names)].filter((name) => name.startsWith(parts[parts.length - 1] ?? ""));
+        return seen.length > 0 ? seen.map((name) => ({ value: name, label: name })) : null;
+      },
+      handler: async (args, ctx) => {
+        const tokens = String(args ?? "").trim().split(/\s+/).filter(Boolean);
+        const flags = new Map<string, string>();
+        const positionals: string[] = [];
+        for (let i = 0; i < tokens.length; i += 1) {
+          if (tokens[i] === "--scope" && tokens[i + 1]) {
+            flags.set("scope", tokens[i + 1]);
+            i += 1;
+            continue;
+          }
+          positionals.push(tokens[i]);
+        }
+        const requested = (positionals.shift() ?? "").toLowerCase();
+        // `list` is what the terminal calls it, and muscle memory arrives here.
+        const action = requested === "list" ? "status" : requested;
+        const name = positionals[0];
+        const scope = flags.get("scope");
+
+        try {
+          if (action === "") {
+            await runMenu(ctx);
+            return;
+          }
+          if (action === "help" || action === "--help") {
+            emit("piagent-mcp-help", mcpActions.help(), ctx);
+            return;
+          }
+          const terminal = mcpActions.terminalOnly(action);
+          if (terminal) {
+            emit("piagent-mcp-terminal", terminal, ctx);
+            return;
+          }
+          if (!ACTIONS.has(action)) {
+            fail(ctx, `unknown subcommand: ${action}. Run /piagent-mcp help.`);
+            return;
+          }
+          if (mcpActions.SERVER_ACTIONS.has(action) && action !== "reset" && !name) {
+            fail(ctx, `${action} needs a server name.`);
+            return;
+          }
+          runAction(ctx, action, name, scope);
+        } catch (error) {
+          fail(ctx, error instanceof Error ? error.message : String(error));
+        }
+      }
+    });
+  }
+  registerMcpCommand();
+
   pi.registerCommand("context-index", {
     description: "Show or search the compact project context index without a model follow-up",
     handler: async (args, ctx) => {

package/packages/piagent-core/mcp/mcp-approval-store.js

@@ -0,0 +1,175 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { stableJson } from "../capabilities/capability-core.js";
+
+// Approval for MCP servers that arrive inside a repository.
+//
+// A repository can carry `.mcp.json` and `.pi/mcp.json`. Cloning one and opening
+// a session should not hand its author a process on this machine with this
+// operator's credentials, so a server found in those files is not usable until
+// somebody here says so.
+//
+// The record lives in the operator's home, never in the repository. That is the
+// whole point: a repository that could approve its own servers has not been
+// gated. It also means a fork, a rename, or a second checkout starts unapproved
+// rather than inheriting a decision made about different code.
+//
+// What is stored is the digest of the entry that was approved. Approval is
+// consent to what the server runs, so a changed command, URL or argument list is
+// a new question — the same split the capability lock draws between what a
+// project consented to and which build produced it.
+
+const STORE_FILE = "piagent-mcp-approvals.json";
+const MAX_STORE_BYTES = 256 * 1024;
+const SCHEMA_VERSION = 1;
+
+/** @param {{home?: string}} [options] @returns {string|undefined} */
+export function approvalStorePath(options = {}) {
+  const base = options.home ?? os.homedir();
+  if (typeof base !== "string" || base.length === 0) return undefined;
+  return path.join(base, ".pi", STORE_FILE);
+}
+
+/**
+ * The digest of a server entry, over the definition only. Two projects that
+ * declare the same server produce the same digest, which is fine: the store is
+ * keyed by project as well, so approving one does not approve the other.
+ *
+ * This is a content identifier, not a credential hash, and SHA-256 is the right
+ * primitive for it. The question it answers is "is this the same definition the
+ * operator approved", so it has to be fast, unsalted and stable across runs —
+ * every property a password hash is deliberately built to lack. Nothing is ever
+ * verified against it, and no secret reaches it: `add` refuses to write a
+ * credential value into MCP config and takes a `${VAR}` reference instead, so
+ * what gets hashed is a command line, a URL, variable names, and an OAuth client
+ * id and scope list, all of which are public identifiers.
+ *
+ * @param {unknown} entry
+ * @returns {string}
+ */
+export function serverEntryDigest(entry) {
+  return `sha256:${crypto.createHash("sha256").update(stableJson(entry)).digest("hex")}`;
+}
+
+/**
+ * A project is identified by its resolved path. Resolved, because a checkout
+ * reached through a symlink is the same checkout, and because macOS reaches
+ * `/var` that way.
+ * @param {string} projectPath
+ * @returns {string}
+ */
+export function projectKey(projectPath) {
+  try {
+    return fs.realpathSync(projectPath);
+  } catch {
+    return path.resolve(projectPath);
+  }
+}
+
+/** @param {{home?: string}} [options] @returns {Record<string, Record<string, {digest?: string, decision?: string, decidedAt?: string}>>} */
+export function readApprovalStore(options = {}) {
+  const file = approvalStorePath(options);
+  if (!file) return {};
+  try {
+    // A store larger than this is not something this code wrote.
+    if (fs.statSync(file).size > MAX_STORE_BYTES) return {};
+    const document = JSON.parse(fs.readFileSync(file, "utf8"));
+    const projects = document?.projects;
+    if (!projects || typeof projects !== "object" || Array.isArray(projects)) return {};
+    return projects;
+  } catch {
+    // An unreadable store denies rather than permits: every server reads as
+    // undecided, which is the state that blocks.
+    return {};
+  }
+}
+
+/**
+ * @param {Record<string, unknown>} projects
+ * @param {{home?: string}} [options]
+ * @returns {boolean}
+ */
+export function writeApprovalStore(projects, options = {}) {
+  const file = approvalStorePath(options);
+  if (!file) return false;
+  const document = { schemaVersion: SCHEMA_VERSION, projects };
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const temporary = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(temporary, `${JSON.stringify(document, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(temporary, file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @typedef {"approved"|"rejected"|"pending"|"changed"} ApprovalState
+ */
+
+/**
+ * What the operator has decided about this server as it is defined right now.
+ *
+ * `changed` is separated from `pending` on purpose. They both block, but they are
+ * different events: one is a server nobody has looked at, the other is a server
+ * that was approved and is no longer what was approved. Collapsing them would
+ * hide the second, which is the one worth reading.
+ *
+ * @param {{projectPath: string, name: string, entry: unknown, store?: Record<string, unknown>, home?: string}} options
+ * @returns {{state: ApprovalState, digest: string, approvedDigest?: string}}
+ */
+export function approvalState(options) {
+  const store = options.store ?? readApprovalStore({ home: options.home });
+  const digest = serverEntryDigest(options.entry);
+  const record = /** @type {Record<string, {digest?: string, decision?: string}>|undefined} */ (
+    store[projectKey(options.projectPath)]
+  )?.[options.name];
+  if (!record || typeof record.decision !== "string") return { state: "pending", digest };
+  if (record.decision === "rejected") return { state: "rejected", digest, approvedDigest: record.digest };
+  if (record.decision !== "approved") return { state: "pending", digest };
+  if (record.digest !== digest) return { state: "changed", digest, approvedDigest: record.digest };
+  return { state: "approved", digest, approvedDigest: record.digest };
+}
+
+/**
+ * @param {{projectPath: string, name: string, entry: unknown, decision: "approved"|"rejected", now?: number, home?: string}} options
+ * @returns {boolean}
+ */
+export function recordApproval(options) {
+  const store = readApprovalStore({ home: options.home });
+  const key = projectKey(options.projectPath);
+  const project = { ...(store[key] ?? {}) };
+  project[options.name] = {
+    decision: options.decision,
+    digest: serverEntryDigest(options.entry),
+    decidedAt: new Date(options.now ?? Date.now()).toISOString()
+  };
+  return writeApprovalStore({ ...store, [key]: project }, { home: options.home });
+}
+
+/**
+ * Drop a decision so the server returns to pending. Used by `piagent-mcp reset`
+ * and when a server is removed, so a later server reusing the name does not
+ * inherit the decision — the digest check would catch it, but leaving a record
+ * for a server that no longer exists is just debris.
+ * @param {{projectPath: string, name?: string, home?: string}} options
+ * @returns {boolean}
+ */
+export function clearApproval(options) {
+  const store = readApprovalStore({ home: options.home });
+  const key = projectKey(options.projectPath);
+  if (!store[key]) return false;
+  if (!options.name) {
+    const { [key]: _removed, ...rest } = store;
+    return writeApprovalStore(rest, { home: options.home });
+  }
+  const { [options.name]: _dropped, ...project } = store[key];
+  const next = Object.keys(project).length > 0 ? { ...store, [key]: project } : (() => {
+    const { [key]: _empty, ...rest } = store;
+    return rest;
+  })();
+  return writeApprovalStore(next, { home: options.home });
+}