@piagent/platform 1.4.0 → 1.5.1

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 = {
@@ -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
+    }
   }
 };
 
@@ -100,7 +179,33 @@ export const CATALOG_PREREQUISITES = {
   ],
   playwright: ["browsers installed on first use (npx playwright install)"],
   figma: ["Piagent approved in the Figma MCP Catalog before remote OAuth can register"],
-  "figma-desktop": ["Figma desktop running with Dev Mode MCP enabled"]
+  "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,6 +218,11 @@ 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: [],
@@ -122,9 +232,24 @@ export const CATALOG_PRESETS = {
   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-desktop"],
-  all: ["context7", "chrome-devtools", "playwright", "github", "figma-desktop", "figma"]
+  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.4.0",
+  "version": "1.5.1",
   "type": "module",
   "private": true,
   "license": "MIT",

package/packages/piagent-core/runtime/hooks/tool-call-hook.ts

@@ -2,6 +2,7 @@ import crypto from "node:crypto";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 import { toolResultFingerprint } from "../../extensions/context-engine.js";
+import { withRemedy } from "../policy/block-remedy.ts";
 import { observeTrajectorySync } from "../trajectory/trajectory-observability.ts";
 import type { TrajectorySyncResult } from "../trajectory/trajectory-runtime.ts";
 
@@ -75,7 +76,13 @@ export function registerToolCallHook(pi: ExtensionAPI, dependencies: ToolCallHoo
       : dependencies.reviewBudgetDecision?.(resolvedEvent, ctx);
     const startDecision = !(decision && typeof decision === "object" && decision.block) ? dependencies.beforeStart?.(resolvedEvent, ctx) : undefined;
     const finalDecision = startDecision && typeof startDecision === "object" && startDecision.block ? startDecision : decision;
-    const blockedDecision = finalDecision && typeof finalDecision === "object" ? finalDecision : undefined;
+    // Every refusal leaves through here, so this is where it is answered. A
+    // remedy attached at the 29 sites that build one is a remedy the next site
+    // will forget.
+    const answered = finalDecision && typeof finalDecision === "object" && finalDecision.block
+      ? withRemedy(finalDecision)
+      : finalDecision;
+    const blockedDecision = answered && typeof answered === "object" ? answered : undefined;
     record(ctx, {
       activityId: `decision:${toolCallId}`,
       event: "tool_decision",
@@ -91,6 +98,6 @@ export function registerToolCallHook(pi: ExtensionAPI, dependencies: ToolCallHoo
       observeTrajectorySync(ctx, dependencies.afterAuthorized?.(resolvedEvent, ctx, { toolCallId }), dependencies.telemetry);
     }
     dependencies.afterDecision?.(resolvedEvent, ctx, { toolCallId, allowed: !blockedDecision?.block, reason: blockedDecision?.reason });
-    return finalDecision;
+    return answered;
   });
 }

package/packages/piagent-core/runtime/input/attachment-document-command.ts

@@ -0,0 +1,39 @@
+import { spawn } from "node:child_process";
+
+import { MAX_DOCUMENT_BYTES, PDF_TIMEOUT_MS, probeExecutableOnPath,
+  type DocumentCommandResult } from "../../extensions/document-intake.ts";
+
+export type AttachmentDocumentCommand = (executable: string, args: string[], input?: Buffer) =>
+DocumentCommandResult | Promise<DocumentCommandResult>;
+
+// The converter is external and may consume its full timeout. Run it without a
+// shell and without blocking Pi's event loop, while bounding both output pipes.
+export function runAttachmentDocumentCommand(executable: string, args: string[], input?: Buffer):
+DocumentCommandResult | Promise<DocumentCommandResult> {
+  if (executable === "command") return probeExecutableOnPath(args[1] ?? "");
+  return new Promise((resolve) => {
+    let child: ReturnType<typeof spawn>;
+    try { child = spawn(executable, args, { stdio: ["pipe", "pipe", "pipe"] }); }
+    catch (cause) { resolve({ status: null, stdout: "", stderr: "", error: cause as Error }); return; }
+    const stdout: Buffer[] = [], stderr: Buffer[] = []; let stdoutBytes = 0, stderrBytes = 0, settled = false;
+    const finish = (result: DocumentCommandResult) => {
+      if (settled) return; settled = true; clearTimeout(timer); resolve(result);
+    };
+    const overflow = () => {
+      child.kill("SIGKILL");
+      const error = new Error("document converter output exceeded its limit"); (error as NodeJS.ErrnoException).code = "ENOBUFS";
+      finish({ status: null, stdout: "", stderr: "", error });
+    };
+    child.stdout.on("data", (chunk: Buffer) => { stdoutBytes += chunk.length; if (stdoutBytes > MAX_DOCUMENT_BYTES) overflow(); else stdout.push(chunk); });
+    child.stderr.on("data", (chunk: Buffer) => { stderrBytes += chunk.length; if (stderrBytes > MAX_DOCUMENT_BYTES) overflow(); else stderr.push(chunk); });
+    child.on("error", (error) => finish({ status: null, stdout: "", stderr: "", error }));
+    child.on("close", (status) => finish({ status, stdout: Buffer.concat(stdout).toString("utf8"), stderr: Buffer.concat(stderr).toString("utf8") }));
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL"); const error = new Error("document converter ETIMEDOUT");
+      finish({ status: null, stdout: "", stderr: "", error });
+    }, PDF_TIMEOUT_MS);
+    timer.unref();
+    child.stdin.on("error", () => undefined);
+    child.stdin.end(input);
+  });
+}

package/packages/piagent-core/runtime/input/attachment-reservation.ts

@@ -0,0 +1,36 @@
+export type AttachmentReservation<T> = {
+  prepared: T;
+  commit(): void;
+  release(): void;
+};
+
+// A small transaction primitive for staged attachments. The map is the lock:
+// only one dispatch may prepare a ref, and only that dispatch may consume it.
+export function reserveAttachments<TRecord extends { attachmentRef: string }, TPrepared>(input: {
+  records: TRecord[];
+  live: Map<string, TRecord>;
+  reservations: Map<string, string>;
+  token: string;
+  prepared: TPrepared;
+  consume(record: TRecord): void;
+}): AttachmentReservation<TPrepared> {
+  for (const record of input.records) input.reservations.set(record.attachmentRef, input.token);
+  let state: "active" | "committed" | "released" = "active";
+  return {
+    prepared: input.prepared,
+    commit: () => {
+      if (state === "committed") return;
+      if (state !== "active" || input.records.some((record) => input.live.get(record.attachmentRef) !== record
+        || input.reservations.get(record.attachmentRef) !== input.token)) throw new Error("attachment-reservation-unavailable");
+      state = "committed";
+      input.records.forEach(input.consume);
+    },
+    release: () => {
+      if (state !== "active") return;
+      state = "released";
+      for (const record of input.records) {
+        if (input.reservations.get(record.attachmentRef) === input.token) input.reservations.delete(record.attachmentRef);
+      }
+    }
+  };
+}