@piagent/platform 1.3.1 → 1.4.1

package/packages/piagent-core/extensions/shell-reach.ts

@@ -0,0 +1,250 @@
+// What a shell command can reach, and how to say so.
+//
+// These checks used to live inside the guard entrypoint, which imports the Pi
+// host runtime and therefore cannot be loaded anywhere else. `piagent explain`
+// needs the same answers the guard gives, and a second implementation of "does
+// this command reach a protected path" is exactly the defect this project keeps
+// closing: one segment, many readers, each with its own view. So the readers
+// live here and both the guard and the CLI take this one.
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  extractShellGlobCandidates,
+  extractShellPathCandidates,
+  matchesProtectedPath,
+  normalizePathCandidate
+} from "./policy-core.js";
+
+export function normalizeRelative(cwd: string, candidate: unknown): string | undefined {
+  if (typeof candidate !== "string" || candidate.trim().length === 0) return undefined;
+  let raw = candidate.trim();
+  try {
+    raw = decodeURIComponent(raw);
+  } catch {
+    return undefined;
+  }
+  if (/^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(raw)) {
+    if (!raw.toLowerCase().startsWith("file://")) return undefined;
+    try {
+      raw = fileURLToPath(raw);
+    } catch {
+      return undefined;
+    }
+  }
+  const absolute = path.isAbsolute(raw) ? raw : path.resolve(cwd, raw);
+  return path.relative(cwd, absolute).split(path.sep).join("/");
+}
+
+export function resolveRepositoryPathCandidate(cwd: string, candidate: string): string | undefined {
+  const normalized = normalizePathCandidate(candidate);
+  if (normalized === ".." || normalized.startsWith("../")) return undefined;
+
+  const relative = path.posix.isAbsolute(normalized)
+    ? path.relative(cwd, normalized).split(path.sep).join("/")
+    : normalized;
+  if (relative === ".." || relative.startsWith("../")) return undefined;
+
+  const pending = relative.split("/").filter((item) => item && item !== ".");
+  let current = cwd;
+  let resolvedDepth = 0;
+  for (let index = 0; index < pending.length; index += 1) {
+    const next = path.join(current, pending[index]);
+    try {
+      fs.lstatSync(next);
+      current = next;
+      resolvedDepth = index + 1;
+    } catch (error) {
+      const code = error && typeof error === "object" && "code" in error ? String((error as { code?: unknown }).code) : "";
+      if (code !== "ENOENT") return undefined;
+      break;
+    }
+  }
+
+  let canonicalBase: string;
+  try {
+    canonicalBase = fs.realpathSync.native(current);
+  } catch {
+    return undefined;
+  }
+  const canonical = path.resolve(canonicalBase, ...pending.slice(resolvedDepth));
+  const canonicalRoot = fs.realpathSync.native(cwd);
+  const canonicalRelative = path.relative(canonicalRoot, canonical).split(path.sep).join("/");
+  if (canonicalRelative === ".." || canonicalRelative.startsWith("../") || path.isAbsolute(canonicalRelative)) return undefined;
+  return canonicalRelative || ".";
+}
+
+export function findResolvedProtectedPathInCommand(
+  cwd: string,
+  command: string,
+  protectedPatterns: string[]
+): { candidate: string; resolved: string; pattern: string } | undefined {
+  for (const candidate of extractShellPathCandidates(command)) {
+    const relative = normalizeRelative(cwd, candidate);
+    if (!relative) continue;
+    const resolved = resolveRepositoryPathCandidate(cwd, relative);
+    if (!resolved || resolved === relative) continue;
+    const pattern = matchesProtectedPath(resolved, protectedPatterns);
+    if (pattern) return { candidate, resolved, pattern };
+  }
+  return undefined;
+}
+
+export function expandSimpleGlobAlternatives(pattern: string, max = 24): { values: string[]; complete: boolean } {
+  let results = [pattern];
+  let changed = true;
+  let complete = true;
+
+  while (changed) {
+    changed = false;
+    const expanded: string[] = [];
+    for (const item of results) {
+      const match = item.match(/\{([^{}]+)\}/);
+      if (!match) {
+        expanded.push(item);
+        continue;
+      }
+      changed = true;
+      const options = match[1].split(",").map((option) => option.trim());
+      for (const option of options) {
+        expanded.push(`${item.slice(0, match.index)}${option}${item.slice((match.index ?? 0) + match[0].length)}`);
+        if (expanded.length >= max) {
+          complete = false;
+          break;
+        }
+      }
+      if (expanded.length >= max) break;
+    }
+    results = expanded.slice(0, max);
+  }
+
+  return { values: results, complete };
+}
+
+export function shellGlobSegmentMatches(patternSegment: string, candidateSegment: string): boolean {
+  if (candidateSegment.startsWith(".") && !patternSegment.startsWith(".")) return false;
+  let source = "";
+  for (let index = 0; index < patternSegment.length; index += 1) {
+    const char = patternSegment[index];
+    if (char === "*") {
+      source += "[^/]*";
+      continue;
+    }
+    if (char === "?") {
+      source += "[^/]";
+      continue;
+    }
+    if (char === "[") {
+      const end = patternSegment.indexOf("]", index + 1);
+      const body = end > index + 1 ? patternSegment.slice(index + 1, end) : "";
+      if (body && /^[!^A-Za-z0-9_-]+$/.test(body)) {
+        const negated = body.startsWith("!") ? `^${body.slice(1)}` : body;
+        source += `[${negated}]`;
+        index = end;
+        continue;
+      }
+    }
+    source += char.replace(/[\\^$.*+?()[\]{}|]/g, "\\$&");
+  }
+  return new RegExp(`^${source}$`, "i").test(candidateSegment);
+}
+
+export function shellGlobMatchesPath(pattern: string, candidate: string): boolean {
+  const patternSegments = normalizePathCandidate(pattern).split("/").filter(Boolean);
+  const candidateSegments = normalizePathCandidate(candidate).split("/").filter(Boolean);
+
+  function match(patternIndex: number, candidateIndex: number): boolean {
+    if (patternIndex === patternSegments.length) return candidateIndex === candidateSegments.length;
+    const patternSegment = patternSegments[patternIndex];
+    if (patternSegment === "**") {
+      if (match(patternIndex + 1, candidateIndex)) return true;
+      for (let next = candidateIndex; next < candidateSegments.length; next += 1) {
+        if (match(patternIndex + 1, next + 1)) return true;
+      }
+      return false;
+    }
+    if (candidateIndex >= candidateSegments.length) return false;
+    return shellGlobSegmentMatches(patternSegment, candidateSegments[candidateIndex])
+      && match(patternIndex + 1, candidateIndex + 1);
+  }
+
+  return patternSegments.length > 0 && candidateSegments.length > 0 && match(0, 0);
+}
+
+export function protectedPatternExamples(pattern: string): string[] {
+  const normalized = normalizePathCandidate(pattern);
+  if (!normalized) return [];
+
+  const examples = new Set<string>();
+  const add = (value: string | undefined) => {
+    const normalizedValue = normalizePathCandidate(value ?? "");
+    if (normalizedValue) examples.add(normalizedValue);
+  };
+
+  add(normalized);
+
+  if (normalized.endsWith("/**")) {
+    const base = normalized.slice(0, -3);
+    add(base);
+    add(`${base}/probe`);
+  }
+
+  if (normalized.startsWith("**/")) {
+    const tail = normalized.slice(3);
+    const concreteTail = tail
+      .replace(/\*\*/g, "nested")
+      .replace(/\*/g, tail.includes(".env.") ? "local" : "probe");
+    add(tail);
+    add(concreteTail);
+    add(`nested/${concreteTail}`);
+  }
+
+  const concrete = normalized
+    .replace(/^\*\*\//, "")
+    .replace(/\/\*\*$/, "/probe")
+    .replace(/\*\*/g, "nested")
+    .replace(/\*/g, normalized.includes(".env.") ? "local" : "probe");
+  add(concrete);
+
+  for (const example of [...examples]) {
+    const base = path.posix.basename(example);
+    if (base && base !== "probe") examples.add(base);
+  }
+
+  return [...examples];
+}
+
+export function shellGlobTargetsProtectedPath(
+  command: string,
+  protectedPatterns: string[]
+): { glob: string; pattern: string; example: string } | undefined {
+  for (const candidate of extractShellGlobCandidates(command)) {
+    if (!/[*?{\[]/.test(candidate)) continue;
+    const expanded = expandSimpleGlobAlternatives(candidate);
+    if (!expanded.complete) return { glob: candidate, pattern: "bounded glob expansion", example: "a protected path" };
+    for (const candidateGlob of expanded.values) {
+      for (const pattern of protectedPatterns) {
+        for (const example of protectedPatternExamples(pattern)) {
+          if (/[*?{\[\]]/.test(example)) continue;
+          if (
+            shellGlobMatchesPath(candidateGlob, example)
+            || shellGlobMatchesPath(`**/${candidateGlob}`, example)
+            || shellGlobMatchesPath(candidateGlob, path.posix.basename(example))
+          ) {
+            return { glob: candidate, pattern, example };
+          }
+        }
+      }
+    }
+  }
+  return undefined;
+}
+
+export 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.";
+}

package/packages/piagent-core/extensions/task-journal.js

@@ -282,6 +282,23 @@ export function appendTaskJournalEventAtMost(cwd, event, options = {}) {
   }
 }
 
+export function transactTaskJournal(cwd, transaction) {
+  if (typeof transaction !== "function") throw new TypeError("Task journal transaction must be a function");
+  const safePaths = writableJournalPaths(cwd);
+  const release = acquireLock(safePaths);
+  try {
+    const journal = recoverIncompleteJournalTail(cwd, safePaths, readTaskJournal(cwd));
+    if (journal.corruptions.length > 0) throw new Error(`Task journal chain is corrupt: ${journal.corruptions[0]}`);
+    const decision = transaction({ events: [...journal.events], head: journal.head ? { ...journal.head } : undefined });
+    if (!decision || typeof decision !== "object" || Array.isArray(decision)) throw new Error("Task journal transaction returned an invalid decision");
+    if (!decision.event) return { appended: false, record: undefined, result: decision.result };
+    const record = appendJournalRecord(safePaths, journal, decision.event, decision.recordedAt);
+    return { appended: true, record, result: decision.result };
+  } finally {
+    release();
+  }
+}
+
 export function readTaskJournal(cwd, options = {}) {
   const paths = taskJournalPaths(cwd);
   let safePath;
@@ -290,7 +307,17 @@ export function readTaskJournal(cwd, options = {}) {
   } catch {
     return { events: [], corruptions: ["journal path is unsafe"], head: undefined };
   }
-  if (!fs.existsSync(safePath)) return { events: [], corruptions: [], head: undefined };
+  if (!fs.existsSync(safePath)) return { events: [], corruptions: [], head: undefined, inputTruncated: false, omittedEvents: 0 };
+  if (Number.isInteger(options.maximumBytes) && options.maximumBytes > 0) {
+    try {
+      const stat = fs.lstatSync(safePath);
+      if (!stat.isFile() || stat.isSymbolicLink() || stat.size > options.maximumBytes) {
+        return { events: [], corruptions: ["journal exceeds bounded inspection size"], head: undefined, inputTruncated: true, omittedEvents: 0 };
+      }
+    } catch {
+      return { events: [], corruptions: ["journal size could not be inspected"], head: undefined, inputTruncated: false, omittedEvents: 0 };
+    }
+  }
   const content = fs.readFileSync(safePath);
   const finalNewline = content.length === 0 || content.at(-1) === 0x0a;
   const lastNewline = finalNewline ? content.length - 1 : content.lastIndexOf(0x0a);
@@ -329,6 +356,8 @@ export function readTaskJournal(cwd, options = {}) {
   return {
     events: visibleEvents,
     corruptions,
+    inputTruncated: visibleEvents.length < events.length,
+    omittedEvents: Math.max(0, events.length - visibleEvents.length),
     recoverableTailBytes,
     validBytes,
     head: events.at(-1)

package/packages/piagent-core/extensions/task-state.js

@@ -66,17 +66,9 @@ export function safeTaskId(value) {
   return normalized || "task";
 }
 
-function stateRoot(cwd) {
-  return path.join(cwd, ".pi", "piagent-state");
-}
-
-function tasksRoot(cwd) {
-  return path.join(stateRoot(cwd), "tasks");
-}
-
-function sessionsRoot(cwd) {
-  return path.join(stateRoot(cwd), "session-tasks");
-}
+function stateRoot(cwd) { return path.join(cwd, ".pi", "piagent-state"); }
+function tasksRoot(cwd) { return path.join(stateRoot(cwd), "tasks"); }
+function sessionsRoot(cwd) { return path.join(stateRoot(cwd), "session-tasks"); }
 
 function taskRunPath(cwd, taskRunId) {
   return path.join(tasksRoot(cwd), `${safeTaskId(taskRunId)}.json`);
@@ -98,7 +90,12 @@ function readJson(cwd, filePath) {
     const safePath = resolveLocalStatePath(cwd, filePath, { label: "Task state", kind: "file" });
     const descriptor = fs.openSync(safePath, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
     try {
-      return JSON.parse(fs.readFileSync(descriptor, "utf8"));
+      const before = fs.fstatSync(descriptor, { bigint: true });
+      if (!before.isFile() || before.size > BigInt(8 * 1024 * 1024)) return undefined;
+      const value = JSON.parse(fs.readFileSync(descriptor, "utf8"));
+      const after = fs.fstatSync(descriptor, { bigint: true });
+      const fields = ["dev", "ino", "mode", "size", "mtimeNs", "ctimeNs"];
+      return fields.every((field) => before[field] === after[field]) ? value : undefined;
     } finally {
       fs.closeSync(descriptor);
     }
@@ -586,7 +583,6 @@ function gitOutput(cwd, args, options = {}) {
     stdio: ["ignore", "pipe", "ignore"]
   });
 }
-
 function gitHasHead(cwd) {
   try {
     gitOutput(cwd, ["rev-parse", "--verify", "HEAD"]);
@@ -595,7 +591,6 @@ function gitHasHead(cwd) {
     return false;
   }
 }
-
 export function isGitWorkingTree(cwd) {
   try {
     return gitOutput(cwd, ["rev-parse", "--is-inside-work-tree"]).trim() === "true";
@@ -603,20 +598,18 @@ export function isGitWorkingTree(cwd) {
     return false;
   }
 }
-
 function normalizedGitPath(value) {
   return String(value ?? "").replaceAll("\\", "/").replace(/^\/+/, "");
 }
-
 function prefixedGitPath(prefix, file) {
   const normalized = normalizedGitPath(file);
   return prefix ? `${prefix}/${normalized}` : normalized;
 }
 
-function workingTreeFilesForGitRoot(cwd) {
+function workingTreeFilesForGitRoot(cwd, observeRename) {
   if (!isGitWorkingTree(cwd)) return [];
   const changed = gitHasHead(cwd)
-    ? changedPathsFromNameStatus(gitOutput(cwd, ["diff", "--name-status", "-z", "--find-renames", "--diff-filter=ACMRD", "HEAD", "--"]))
+    ? changedPathsFromNameStatus(gitOutput(cwd, ["diff", "--name-status", "-z", "--find-renames", "--diff-filter=ACMRD", "HEAD", "--"]), observeRename)
     : gitOutput(cwd, ["ls-files", "-z"]).split("\0").filter(Boolean);
   const untracked = gitOutput(cwd, ["ls-files", "--others", "--exclude-standard", "-z"]).split("\0").filter(Boolean);
   return [...new Set([...changed, ...untracked].map(normalizedGitPath).filter((item) => item && !item.startsWith(".pi/piagent-state/")))].sort();
@@ -694,9 +687,7 @@ function nonGitWorkspaceFiles(cwd, gitRootPrefixes) {
   return files.sort();
 }
 
-function nonGitWorkspaceFileDigest(cwd, file) {
-  return streamedWorkingTreeFileDigest(cwd, file, false);
-}
+function nonGitWorkspaceFileDigest(cwd, file, protectedProjectPath = null) { return streamedWorkingTreeFileDigest(cwd, file, false, protectedProjectPath); }
 
 function pathWithinNonGitWorkspaceEvidenceRoot(candidate, gitRootPrefixes) {
   const topSegment = candidate.split("/")[0];
@@ -777,7 +768,7 @@ export function repositoryFileManifest(cwd, maxFiles = 10_000) {
   return [...new Set(files)].sort();
 }
 
-function changedPathsFromNameStatus(output) {
+function changedPathsFromNameStatus(output, observeRename) {
   const fields = String(output ?? "").split("\0").filter(Boolean);
   const files = [];
   for (let index = 0; index < fields.length;) {
@@ -787,7 +778,7 @@ function changedPathsFromNameStatus(output) {
     files.push(source);
     if (/^[RC]/.test(status)) {
       const destination = fields[index++];
-      if (destination) files.push(destination);
+      if (destination) { files.push(destination); observeRename?.(source, destination); }
     }
   }
   return files;
@@ -804,8 +795,12 @@ export function workingTreeSnapshotHasUnavailableEvidence(snapshot) {
   return Object.values(snapshot ?? {}).some((digest) => isUnavailableWorkingTreeDigest(digest));
 }
 
-function streamedWorkingTreeFileDigest(root, file, hasHead) {
+function streamedWorkingTreeFileDigest(root, file, hasHead, protectedProjectPath = null) {
   const absolute = path.resolve(root, file);
+  if (protectedProjectPath) {
+    try { return unavailableWorkingTreeDigest(protectedProjectPath, "protected-path", fs.lstatSync(absolute)); }
+    catch { return unavailableWorkingTreeDigest(protectedProjectPath, "protected-path"); }
+  }
   const relative = path.relative(root, absolute);
   if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
     return unavailableWorkingTreeDigest(file, "outside-root");
@@ -866,22 +861,24 @@ function streamedWorkingTreeFileDigest(root, file, hasHead) {
   }
 }
 
-export function workingTreeSnapshot(cwd) {
+export function workingTreeSnapshot(cwd, options = {}) {
   const snapshot = {};
+  const isProtectedProjectPath = typeof options.isProtectedProjectPath === "function" ? options.isProtectedProjectPath : () => false;
   const roots = gitEvidenceRoots(cwd);
   for (const root of roots) {
-    const hasHead = gitHasHead(root.cwd);
-    for (const file of workingTreeFilesForGitRoot(root.cwd)) {
-      const snapshotPath = prefixedGitPath(root.prefix, file);
-      snapshot[snapshotPath] = streamedWorkingTreeFileDigest(root.cwd, file, hasHead);
+    const protectedAliases = new Set();
+    const observeRename = (source, destination) => {
+      const paths = [source, destination];
+      if (paths.some((file) => file === ".pi/piagent-state" || file.startsWith(".pi/piagent-state/") || isProtectedProjectPath(prefixedGitPath(root.prefix, file))))
+        paths.forEach((file) => protectedAliases.add(file));
+    };
+    const hasHead = gitHasHead(root.cwd); for (const file of workingTreeFilesForGitRoot(root.cwd, observeRename)) {
+      const projectPath = prefixedGitPath(root.prefix, file);
+      snapshot[projectPath] = streamedWorkingTreeFileDigest(root.cwd, file, hasHead, isProtectedProjectPath(projectPath) || protectedAliases.has(file) ? projectPath : null);
     }
-  }
-  if (!isGitWorkingTree(cwd) && roots.length > 0) {
-    for (const file of nonGitWorkspaceFiles(cwd, roots.map((root) => root.prefix))) {
-      snapshot[file] = nonGitWorkspaceFileDigest(cwd, file);
-    }
-  }
-  return snapshot;
+  } if (!isGitWorkingTree(cwd) && roots.length > 0) for (const file of nonGitWorkspaceFiles(cwd, roots.map((root) => root.prefix))) {
+      snapshot[file] = nonGitWorkspaceFileDigest(cwd, file, isProtectedProjectPath(file) ? file : null);
+  } return snapshot;
 }
 
 export function taskStateMigrationStatus(cwd) {

package/packages/piagent-core/mcp/mcp-command-actions.js

@@ -37,7 +37,7 @@ export const SERVER_ACTIONS = new Set(["get", "approve", "reject", "reset", "ena
 export const TERMINAL_ONLY = new Map([
   ["add", "piagent-mcp add <name> [--scope <scope>] --url <url> | -- <command> [args...]"],
   ["remove", "piagent-mcp remove <name> --scope <scope>"],
-  ["preset", "piagent-mcp --preset <core|popular|design> --scope <scope>"]
+  ["preset", "piagent-mcp --preset <core|popular|documents|google|design> --scope <scope>"]
 ]);
 
 export const HELP_LINES = [

package/packages/piagent-core/mcp/mcp-server-catalog.js

@@ -6,7 +6,7 @@
 // Nothing here is a secret. Every credential is referenced as an environment
 // variable, so the config can be read, diffed and committed without leaking one.
 
-/** @typedef {{description: string, config: Record<string, unknown>}} CatalogServer */
+/** @typedef {{description: string, maturity?: "stable"|"experimental", config: Record<string, unknown>}} CatalogServer */
 
 /** @type {Record<string, CatalogServer>} */
 export const CATALOG_SERVERS = {
@@ -68,7 +68,7 @@ export const CATALOG_SERVERS = {
     }
   },
   figma: {
-    description: "Figma remote MCP server. Requires Figma OAuth from the MCP panel when first used.",
+    description: "Figma remote MCP server. OAuth works only for clients approved in the Figma MCP Catalog.",
     config: {
       url: "https://mcp.figma.com/mcp",
       auth: "oauth",
@@ -83,6 +83,85 @@ export const CATALOG_SERVERS = {
       lifecycle: "lazy",
       directTools: false
     }
+  },
+  // Google's own remote servers, one per product, rather than a community server
+  // holding every scope at once: a session that only needs to read a document
+  // should not be one OAuth grant away from the mailbox.
+  //
+  // These carry no version pin because there is nothing local to pin -- the
+  // endpoint is operated by Google and changes under the same URL. That is a
+  // real difference from every command-based server above, where the pin is what
+  // stops a floating tag becoming a supply-chain decision each session.
+  // Scopes are declared read-only. Write access is one word longer to ask for
+  // and cannot be taken back once an agent has used it, so the default grant is
+  // the one that cannot lose anything. `clientId` is deliberately absent: every
+  // operator registers their own OAuth client, and a client id baked in here
+  // would be someone else's project answering for their consent screen.
+  "google-drive": {
+    description: "EXPERIMENTAL Developer Preview: Google Drive remote MCP server. Read-only by default.",
+    maturity: "experimental",
+    config: {
+      url: "https://drivemcp.googleapis.com/mcp/v1",
+      auth: "oauth",
+      oauth: { scopes: ["https://www.googleapis.com/auth/drive.readonly"] },
+      lifecycle: "lazy",
+      directTools: false
+    }
+  },
+  gmail: {
+    description: "EXPERIMENTAL Developer Preview: Gmail remote MCP server. Read-only by default.",
+    maturity: "experimental",
+    config: {
+      url: "https://gmailmcp.googleapis.com/mcp/v1",
+      auth: "oauth",
+      oauth: { scopes: ["https://www.googleapis.com/auth/gmail.readonly"] },
+      lifecycle: "lazy",
+      directTools: false
+    }
+  },
+  "google-docs": {
+    description: "EXPERIMENTAL Developer Preview: Google Docs remote MCP server. Read-only by default.",
+    maturity: "experimental",
+    config: {
+      url: "https://docsmcp.googleapis.com/mcp/v1",
+      auth: "oauth",
+      oauth: {
+        scopes: [
+          "https://www.googleapis.com/auth/documents.readonly",
+          "https://www.googleapis.com/auth/drive.readonly"
+        ]
+      },
+      lifecycle: "lazy",
+      directTools: false
+    }
+  },
+  "google-sheets": {
+    description: "EXPERIMENTAL Developer Preview: Google Sheets remote MCP server. Read-only by default.",
+    maturity: "experimental",
+    config: {
+      url: "https://sheetsmcp.googleapis.com/mcp/v1",
+      auth: "oauth",
+      oauth: {
+        scopes: [
+          "https://www.googleapis.com/auth/spreadsheets.readonly",
+          "https://www.googleapis.com/auth/drive.readonly"
+        ]
+      },
+      lifecycle: "lazy",
+      directTools: false
+    }
+  },
+  // Converts .docx, .xlsx, .pptx and .pdf to Markdown locally. Local matters:
+  // the alternative to this is uploading a document somewhere to read it, and a
+  // document worth converting is usually one worth not uploading.
+  markitdown: {
+    description: "MarkItDown MCP. Converts local docx, xlsx, pptx, pdf and html files to Markdown. Runs offline for file: URIs.",
+    config: {
+      command: "uvx",
+      args: ["markitdown-mcp@0.0.1a4"],
+      lifecycle: "lazy",
+      directTools: false
+    }
   }
 };
 
@@ -99,8 +178,34 @@ export const CATALOG_PREREQUISITES = {
     "export GITHUB_PERSONAL_ACCESS_TOKEN with the scopes you intend to use"
   ],
   playwright: ["browsers installed on first use (npx playwright install)"],
-  figma: ["Figma OAuth, completed from the Pi MCP panel on first use"],
-  "figma-desktop": ["Figma desktop running with Dev Mode MCP enabled"]
+  figma: ["Piagent approved in the Figma MCP Catalog before remote OAuth can register"],
+  "figma-desktop": ["Figma desktop running with Dev Mode MCP enabled"],
+  "google-drive": [
+    "a Google Cloud project with drive.googleapis.com and drivemcp.googleapis.com enabled",
+    "Developer Preview: no Pi OAuth end-to-end release proof exists yet",
+    "Google's supported client guides use an OAuth client id and secret; Pi's public-client/PKCE compatibility is unverified",
+    "piagent-mcp add google-drive --url https://drivemcp.googleapis.com/mcp/v1 --oauth-client-id <id> --scope user"
+  ],
+  gmail: [
+    "a Google Cloud project with gmail.googleapis.com and gmailmcp.googleapis.com enabled",
+    "Developer Preview: no Pi OAuth end-to-end release proof exists yet",
+    "Google's supported client guides use an OAuth client id and secret; Pi's public-client/PKCE compatibility is unverified",
+    "read the warning in docs/mcp-and-tools.md first: mail is untrusted input reaching an agent that can act"
+  ],
+  "google-docs": [
+    "a Google Cloud project with docs.googleapis.com and docsmcp.googleapis.com enabled",
+    "Developer Preview: no Pi OAuth end-to-end release proof exists yet",
+    "Google's supported client guides use an OAuth client id and secret; Pi's public-client/PKCE compatibility is unverified"
+  ],
+  "google-sheets": [
+    "a Google Cloud project with sheets.googleapis.com and sheetsmcp.googleapis.com enabled",
+    "Developer Preview: no Pi OAuth end-to-end release proof exists yet",
+    "Google's supported client guides use an OAuth client id and secret; Pi's public-client/PKCE compatibility is unverified"
+  ],
+  markitdown: [
+    "uv on PATH (https://docs.astral.sh/uv); the first run downloads a Python runtime and roughly 120 MB of dependencies",
+    "note: markitdown-mcp is published as an alpha, so pin changes deliberately"
+  ]
 };
 
 // Variables a pinned server references but works without. Context7 answers
@@ -113,18 +218,38 @@ export const CATALOG_OPTIONAL_ENV = {
   context7: ["CONTEXT7_API_KEY"]
 };
 
+// `core` is what an install writes when nobody names a preset, and `popular` is
+// what somebody picks without reading the list. Neither may reach a mailbox or a
+// Drive: an install that quietly grants those is a decision the operator never
+// made. The Google servers are therefore only in presets somebody has to type,
+// and in `all`, which means what it says.
 /** @type {Record<string, string[]>} */
 export const CATALOG_PRESETS = {
   minimal: [],
   docs: ["context7"],
   browser: ["chrome-devtools", "playwright"],
   github: ["github"],
-  design: ["figma"],
+  design: ["figma-desktop"],
   "design-local": ["figma-desktop"],
   web: ["context7", "chrome-devtools", "playwright"],
+  // The generic documents preset stays local. Google Workspace is Developer
+  // Preview and must be selected through an explicitly named Google preset.
+  documents: ["markitdown"],
+  // One preset per product, because that is why Google ships four servers
+  // instead of one. Bundling them back together would mean reading a
+  // spreadsheet costs a grant over Drive and every document in it.
+  "google-drive": ["google-drive"],
+  "google-docs": ["google-docs"],
+  "google-sheets": ["google-sheets"],
+  "google-mail": ["gmail"],
+  google: ["google-drive", "google-docs", "google-sheets"],
+  "google-all": ["google-drive", "gmail", "google-docs", "google-sheets"],
   core: ["context7", "chrome-devtools", "github"],
-  popular: ["context7", "chrome-devtools", "playwright", "github", "figma"],
-  all: ["context7", "chrome-devtools", "playwright", "github", "figma", "figma-desktop"]
+  popular: ["context7", "chrome-devtools", "playwright", "github", "figma-desktop"],
+  all: [
+    "context7", "chrome-devtools", "playwright", "github", "figma-desktop", "figma",
+    "markitdown", "google-drive", "gmail", "google-docs", "google-sheets"
+  ]
 };
 
 /** @param {string} name @returns {boolean} */
@@ -136,7 +261,7 @@ export function isCatalogPreset(name) {
  * The servers a preset installs, with their definitions resolved. Throws on an
  * unknown preset so a typo is refused before anything is written.
  * @param {string} name
- * @returns {{name: string, config: Record<string, unknown>, requires: string[]}[]}
+ * @returns {{name: string, maturity: "stable"|"experimental", config: Record<string, unknown>, requires: string[]}[]}
  */
 export function resolvePreset(name) {
   if (!isCatalogPreset(name)) {
@@ -145,6 +270,11 @@ export function resolvePreset(name) {
   return CATALOG_PRESETS[name].map((serverName) => {
     const server = CATALOG_SERVERS[serverName];
     if (!server) throw new Error(`preset ${name} references missing server ${serverName}`);
-    return { name: serverName, config: server.config, requires: CATALOG_PREREQUISITES[serverName] ?? [] };
+    return {
+      name: serverName,
+      maturity: server.maturity ?? "stable",
+      config: server.config,
+      requires: CATALOG_PREREQUISITES[serverName] ?? []
+    };
   });
 }

package/packages/piagent-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piagent/core",
-  "version": "1.3.1",
+  "version": "1.4.1",
   "type": "module",
   "private": true,
   "license": "MIT",