@piagent/platform 1.1.9 → 1.2.1

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";
@@ -11,6 +12,7 @@ import {
   extractShellGlobCandidates,
   extractShellPathCandidates,
   findProtectedPathInCommand,
+  unresolvedPathExpansions,
   globMatchesPath,
   matchesProtectedPath,
   normalizePathCandidate,
@@ -41,6 +43,17 @@ import {
 } from "./redaction-core.js";
 import { detectProfileName } from "./project-shape.js";
 import { evaluateUpdateCheck, isInstalledPlatform, readUpdateCache, startUpdateProbe } from "./update-check.js";
+import {
+  REPOSITORY_SCOPES,
+  collectServers,
+  configPathForScope,
+  mcpDecisionInputs,
+  unverifiableMcpConfig
+} from "../mcp/mcp-config-layers.js";
+import { attributeDirectTool } from "../mcp/mcp-tool-naming.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 +454,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 +2001,155 @@ 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, under
+// directTools, one tool per server tool named `<prefix>_<tool>` where the prefix
+// is derived from the server name. Direct names are matched against the servers
+// this gate is holding rather than against a fixed pattern, because the prefix
+// is the server's own name and there is nothing constant to anchor on.
+function mcpServerFromToolCall(
+  toolName: string,
+  input: Record<string, unknown>,
+  candidates: Iterable<string>
+): string | undefined {
+  if (normalizeActionToken(toolName) === "mcp") {
+    return typeof input.server === "string" && input.server.trim() ? input.server.trim() : undefined;
+  }
+  return attributeDirectTool(toolName, candidates);
+}
+
+// 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.
+interface RepositoryMcpGate {
+  blocked: Map<string, { state: string; origin: string }>;
+  // Conditions under which no tool call can be checked at all, each with the
+  // sentence to show. These are not "a server is unapproved" — they are "this
+  // repository's config has put the gate in a state where it cannot tell which
+  // server a call belongs to", and the only sound answer to that is to stop.
+  unverifiable: string[];
+}
+
+const mcpApprovalCache = new Map<string, { signature: string; gate: RepositoryMcpGate }>();
+
+function repositoryMcpGate(cwd: string): RepositoryMcpGate {
+  // Repository scopes plus anything an `imports` key drags in from a file the
+  // clone carries. Collecting those here is the whole point: a server the gate
+  // never enumerates is a server it silently permits.
+  const servers = collectServers({ projectPath: cwd, scopes: [...REPOSITORY_SCOPES] });
+  const repositoryFiles = [...REPOSITORY_SCOPES].map((scope) => ({
+    scope,
+    file: configPathForScope(scope, { projectPath: cwd })
+  }));
+  // Every file the decision reads, listed by the module that reads them rather
+  // than restated here. Building this by hand is what went wrong: the scan grew
+  // to read merged settings from all four scopes and to stat import targets
+  // outside the repository, the hand-written list did not, and an already-loaded
+  // guard went on permitting calls after a personal global config had put the
+  // session in the state this gate exists to refuse.
+  const signature = [
+    ...servers.map((server) => `${server.origin}:${server.name}:${fileSignature(server.file)}`),
+    ...repositoryFiles.map((layer) => `layer:${layer.scope}:${fileSignature(layer.file)}`),
+    ...mcpDecisionInputs({ projectPath: cwd }).map((file) => `input:${file}:${fileSignature(file)}`),
+    `store:${fileSignature(path.join(os.homedir(), ".pi", "piagent-mcp-approvals.json"))}`
+  ].join("|");
+  const cached = mcpApprovalCache.get(cwd);
+  if (cached?.signature === signature) return cached.gate;
+
+  const blocked = new Map<string, { state: string; origin: string }>();
+  for (const server of servers) {
+    const state = approvalState({ projectPath: cwd, name: server.name, entry: server.entry });
+    if (state.state === "approved") continue;
+    // A name defined more than once keeps its blocking entry: the approved copy
+    // does not vouch for the one nobody has looked at.
+    blocked.set(server.name, { state: state.state, origin: server.origin });
+  }
+
+  // Two things a repository-carried config can do that leave nothing to check.
+  //
+  // It can ask for tools with no prefix, so a direct tool arrives under a bare
+  // name carrying no evidence of its server. Refusing only the proxy there was
+  // not a fix: the proxy is the one form that names its server, so blocking it
+  // and allowing the bare names left the hole exactly where it was.
+  //
+  // It can also import a kind whose config this platform cannot enumerate, and
+  // then the set of servers reaching the session is simply unknown. Blocking the
+  // servers that could be listed says nothing about the ones that could not.
+  //
+  // Both stop every tool call. A repository can make a session refuse to run;
+  // it must not be able to make one run a server nobody approved.
+  // Read from the shared module rather than decided here, so `piagent-mcp
+  // doctor` reports exactly what this refuses. The two disagreeing is how an
+  // operator ends up reading "PASS" while every tool call is being stopped.
+  const unverifiable = unverifiableMcpConfig({ projectPath: cwd }).map((problem) => problem.detail);
+
+  const gate = { blocked, unverifiable };
+  mcpApprovalCache.set(cwd, { signature, gate });
+  return gate;
+}
+
+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 gate = repositoryMcpGate(cwd);
+
+  // Every tool call, not only the ones that look like MCP. Under either of these
+  // conditions a call cannot be traced to a server, so there is no such thing as
+  // a call this gate can clear.
+  if (gate.unverifiable.length > 0) {
+    return { block: true, reason: `Blocked every tool call: ${gate.unverifiable.join(" ")}` };
+  }
+
+  const server = mcpServerFromToolCall(toolName, input, gate.blocked.keys());
+  if (!server) return { block: false };
+  const record = gate.blocked.get(server);
+  if (!record) return { block: false };
+  const explanation = record.state === "rejected"
+    ? "it was rejected for this project"
+    : record.state === "changed"
+      ? "its definition changed since it was approved"
+      : record.origin.startsWith("import:")
+        ? `this repository imports it from ${record.origin.slice("import:".length)} config and nobody on this machine has approved it here`
+        : "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.`
+  };
+}
+
+// A word whose final path segment glues literal text onto an expansion --
+// `.en$(echo v)`, `${D}.env` -- names a file this process cannot know without
+// running the substitution. Matching the literal half against the protected
+// patterns answers a different question than the one being asked, so refuse
+// rather than let an unknown filename through unchecked.
+function unresolvedExpansionReason(subject: string, words: string[]): string {
+  const listed = words.map((word) => `\`${word}\``).join(", ");
+  return `${subject} builds a filename this guard cannot resolve: ${listed}. `
+    + "The literal text around the expansion makes it a path, but its value is only known at run time, "
+    + "so it cannot be checked against the protected paths. Write the path out, or put the expansion in its own argument.";
+}
+
 function evaluateMcpProxyShellProtectedAccess(
   cwd: string,
   prepared: PreparedToolInput,
@@ -2015,6 +2193,10 @@ function evaluateMcpProxyShellProtectedAccess(
       reason: `MCP command resolves to protected path: ${resolvedProtectedHit.candidate} resolves to ${resolvedProtectedHit.resolved} matching ${resolvedProtectedHit.pattern}`
     };
   }
+  const unresolved = protectedPaths.length > 0 ? unresolvedPathExpansions(command) : [];
+  if (unresolved.length > 0) {
+    return { block: true, reason: unresolvedExpansionReason("MCP command", unresolved) };
+  }
   return { block: false };
 }
 
@@ -3187,6 +3369,19 @@ function modelLabel(ctx: ExtensionContext): string {
   return model.name ?? model.id ?? "unknown";
 }
 
+function currentSessionName(ctx: ExtensionContext): string {
+  try {
+    return String(ctx.sessionManager.getSessionName() ?? "").trim();
+  } catch {
+    return "";
+  }
+}
+
+function hasOperatorSessionName(name: string): boolean {
+  const normalized = name.trim().toLowerCase();
+  return Boolean(normalized && normalized !== "session");
+}
+
 function buildUsageSnapshot(ctx: ExtensionContext, thinkingLevel?: string): UsageSnapshot {
   const contextUsage = ctx.getContextUsage();
   const contextWithThinking = ctx as ExtensionContext & { getThinkingLevel?: () => string };
@@ -3213,7 +3408,8 @@ function buildUsageSnapshot(ctx: ExtensionContext, thinkingLevel?: string): Usag
       availableInCommand: false,
       howToRead: [
         "Inside Pi TUI: run /session for exact tokens and cost.",
-        "Outside Pi: run piagent-usage /path/to/project or scripts/pi-session-stats.sh /path/to/project."
+        "Outside Pi: run piagent-usage /path/to/project or scripts/pi-session-stats.sh /path/to/project.",
+        "Historical totals: run piagent-usage --history /path/to/project --days 7."
       ]
     }
   };
@@ -3241,6 +3437,12 @@ function formatUsageSnapshot(snapshot: UsageSnapshot): string {
     "",
     "```bash",
     "piagent-usage /path/to/project",
+    "```",
+    "",
+    "Historical totals / weekly report:",
+    "",
+    "```bash",
+    "piagent-usage --history /path/to/project --days 7",
     "```"
   ].join("\n");
 }
@@ -3726,7 +3928,10 @@ export default function piagentGuard(pi: ExtensionAPI) {
     const explicitProfile = Boolean(process.env.PIAGENT_PROFILE?.trim());
     const profile = loadProfile(ctx.cwd, projectTrusted);
     const name = profile.displayName || profile.projectId || path.basename(ctx.cwd);
-    pi.setSessionName(`pi:${name}`);
+    const operatorSessionName = currentSessionName(ctx);
+    if (!hasOperatorSessionName(operatorSessionName)) {
+      pi.setSessionName(`pi:${name}`);
+    }
     const profileHint = explicitProfile || (projectTrusted && fs.existsSync(projectProfilePath(ctx.cwd)))
       ? ""
       : " (run /onboard-project to select a profile)";
@@ -3751,6 +3956,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 +4119,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) {
@@ -3939,6 +4155,12 @@ export default function piagentGuard(pi: ExtensionAPI) {
           reason: `Command resolves to protected path: ${resolvedProtectedHit.candidate} resolves to ${resolvedProtectedHit.resolved} matching ${resolvedProtectedHit.pattern}`
         };
       }
+      const unresolvedExpansions = pathPolicy.shellProtectedPaths.length > 0
+        ? unresolvedPathExpansions(command)
+        : [];
+      if (unresolvedExpansions.length > 0) {
+        return { block: true, reason: unresolvedExpansionReason("Command", unresolvedExpansions) };
+      }
 
       const confirmationReasons = execDecision.mode !== "off" && execDecision.decision === "prompt"
         ? [...execDecision.reasons]
@@ -5720,6 +5942,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) => {