@simonepri/refined-antigravity-acp 0.1.0

package/server/mcp-proxy.ts

@@ -0,0 +1,375 @@
+import fs from "node:fs";
+import http from "node:http";
+import https from "node:https";
+import os from "node:os";
+import path from "node:path";
+
+/**
+ * Protocol versions the target MCP server understands. Paseo's daemon embeds
+ * `@modelcontextprotocol/sdk`, whose streamable-HTTP transport rejects any request
+ * carrying an `MCP-Protocol-Version` header outside this list with HTTP 400.
+ */
+export const DEFAULT_SUPPORTED_PROTOCOL_VERSIONS = [
+  "2025-11-25",
+  "2025-06-18",
+  "2025-03-26",
+  "2024-11-05",
+  "2024-10-07",
+] as const;
+
+/** Headers that are meaningful only for a single hop and must not be forwarded. */
+const HOP_BY_HOP_HEADERS = [
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade",
+];
+
+export interface McpProxyOptions {
+  /** Versions the upstream accepts. Anything else is rewritten to `fallbackProtocolVersion`. */
+  supportedProtocolVersions?: readonly string[];
+  /** Version substituted when the client asks for one the upstream does not support. */
+  fallbackProtocolVersion?: string;
+  /**
+   * File used to remember the listening port across restarts. Antigravity persists the
+   * MCP server URL into its per-session SQLite database, so a session resumed after a
+   * daemon restart still points at whatever port we used when it was created.
+   */
+  portFile?: string | null;
+}
+
+function defaultPortFile(): string {
+  const base =
+    process.env.PASEO_PLUGIN_DATA_DIR ?? path.join(os.homedir(), ".paseo", "plugin-data");
+  return path.join(base, "antigravity", "mcp-proxy-ports.json");
+}
+
+function readPortFile(file: string): Record<string, number> {
+  try {
+    const parsed: unknown = JSON.parse(fs.readFileSync(file, "utf-8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+    return Object.fromEntries(
+      Object.entries(parsed as Record<string, unknown>).filter(
+        ([, v]) => typeof v === "number" && Number.isInteger(v) && v > 0 && v < 65536,
+      ) as Array<[string, number]>,
+    );
+  } catch {
+    return {};
+  }
+}
+
+function writePortFile(file: string, origin: string, port: number): void {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify({ ...readPortFile(file), [origin]: port }, null, 2));
+  } catch {
+    // A missing port file only costs us port stability, never correctness.
+  }
+}
+
+function sendJsonRpcError(res: http.ServerResponse, statusCode: number, message: string): void {
+  if (res.headersSent) return;
+  const payload = JSON.stringify({
+    jsonrpc: "2.0",
+    error: {
+      code: -32603,
+      message,
+    },
+    id: null,
+  });
+  res.writeHead(statusCode, {
+    "Content-Type": "application/json",
+    "Content-Length": Buffer.byteLength(payload),
+  });
+  res.end(payload);
+}
+
+interface JsonRpcDescription {
+  isNotification: boolean;
+  method: string | null;
+}
+
+function describeJsonRpc(body: Buffer): JsonRpcDescription {
+  if (body.length === 0) return { isNotification: false, method: null };
+  try {
+    const parsed: unknown = JSON.parse(body.toString("utf-8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return { isNotification: false, method: null };
+    }
+    const { method, id } = parsed as Record<string, unknown>;
+    const methodName = typeof method === "string" ? method : null;
+    return {
+      isNotification: methodName !== null && id === undefined,
+      method: methodName,
+    };
+  } catch {
+    return { isNotification: false, method: null };
+  }
+}
+
+function formatNotificationAbsorbLog(statusCode: number, method: string | null): string {
+  const methodLabel = method ? '"' + method + '"' : "unknown";
+  const base =
+    "[paseo-antigravity][mcp-proxy] Absorbed upstream " +
+    statusCode +
+    " on notification " +
+    methodLabel +
+    "; replied 202 so go-sdk does not tear the session down";
+  if (method === "notifications/cancelled") {
+    return base;
+  }
+  return base + " (indicates proxy normalization bug; investigate)";
+}
+
+function normalizeAccept(rawAccept: string | string[] | undefined): string {
+  const accept = Array.isArray(rawAccept) ? rawAccept.join(", ") : rawAccept;
+  if (!accept || !accept.includes("application/json") || !accept.includes("text/event-stream")) {
+    return "application/json, text/event-stream";
+  }
+  return accept;
+}
+
+/**
+ * A loopback reverse proxy for a single upstream MCP origin.
+ *
+ * Google's `agy_acp_server` ships an MCP client that advertises protocol version
+ * `2026-07-28`, which Paseo's daemon rejects with HTTP 400 on every request after
+ * `initialize`. This proxy normalizes that header down to a version the upstream
+ * accepts, turning a hard transport failure into ordinary version negotiation.
+ *
+ * It is origin-bound and forwards the request path and query verbatim, so
+ * `?callerAgentId=...` survives and the client's OAuth discovery probes
+ * (`/.well-known/oauth-protected-resource/...`) reach the real upstream path
+ * instead of being collapsed onto the MCP endpoint.
+ */
+export class McpProxy {
+  private server: http.Server | null = null;
+  private port: number | null = null;
+  private readonly origin: URL;
+  private readonly supportedProtocolVersions: ReadonlySet<string>;
+  private readonly fallbackProtocolVersion: string;
+  private readonly portFile: string | null;
+
+  constructor(origin: string, options: McpProxyOptions = {}) {
+    this.origin = new URL(origin);
+    this.supportedProtocolVersions = new Set(
+      options.supportedProtocolVersions ?? DEFAULT_SUPPORTED_PROTOCOL_VERSIONS,
+    );
+    this.fallbackProtocolVersion =
+      options.fallbackProtocolVersion ?? DEFAULT_SUPPORTED_PROTOCOL_VERSIONS[0];
+    this.portFile = options.portFile === undefined ? defaultPortFile() : options.portFile;
+  }
+
+  private buildForwardHeaders(
+    req: http.IncomingMessage,
+    bodyLength: number,
+  ): http.OutgoingHttpHeaders {
+    const headers: http.OutgoingHttpHeaders = { ...req.headers };
+    delete headers.host;
+    for (const name of HOP_BY_HOP_HEADERS) delete headers[name];
+
+    const version = req.headers["mcp-protocol-version"];
+    if (typeof version === "string" && !this.supportedProtocolVersions.has(version)) {
+      headers["mcp-protocol-version"] = this.fallbackProtocolVersion;
+    }
+
+    headers.accept = normalizeAccept(req.headers.accept);
+
+    if (bodyLength > 0) {
+      if (!headers["content-type"]) {
+        headers["content-type"] = "application/json";
+      }
+      headers["content-length"] = bodyLength;
+    }
+
+    return headers;
+  }
+
+  private handleProxyResponse(
+    res: http.ServerResponse,
+    proxyRes: http.IncomingMessage,
+    rpcDesc: JsonRpcDescription,
+  ): void {
+    const statusCode = proxyRes.statusCode ?? 502;
+    if (rpcDesc.isNotification && statusCode >= 400 && statusCode < 500) {
+      console.error(formatNotificationAbsorbLog(statusCode, rpcDesc.method));
+      proxyRes.resume();
+      res.writeHead(202, { "Content-Length": "0" });
+      res.end();
+      return;
+    }
+
+    res.writeHead(statusCode, proxyRes.headers);
+    // MCP responses are often `text/event-stream`; without an explicit flush the
+    // headers can sit in Node's buffer until the first chunk, stalling the client.
+    res.flushHeaders();
+    proxyRes.pipe(res);
+  }
+
+  private forwardRequest(req: http.IncomingMessage, res: http.ServerResponse, body: Buffer): void {
+    const isTls = this.origin.protocol === "https:";
+    const transport = isTls ? https : http;
+    const rpcDesc = describeJsonRpc(body);
+
+    const proxyReq = transport.request(
+      {
+        protocol: this.origin.protocol,
+        hostname: this.origin.hostname,
+        port: this.origin.port || (isTls ? 443 : 80),
+        method: req.method,
+        // Verbatim path + query. The upstream owns its own routing.
+        path: req.url,
+        headers: this.buildForwardHeaders(req, body.length),
+      },
+      (proxyRes) => this.handleProxyResponse(res, proxyRes, rpcDesc),
+    );
+
+    proxyReq.on("error", (err) => {
+      sendJsonRpcError(res, 502, `MCP proxy error: ${err.message}`);
+    });
+    // Long-lived SSE streams must not be reaped by the default socket timeout.
+    proxyReq.setTimeout(0);
+    res.on("close", () => proxyReq.destroy());
+
+    proxyReq.end(body);
+  }
+
+  /**
+   * Buffering the request body in memory is safe and necessary because MCP JSON-RPC
+   * messages are small (typically <1MB) and buffering allows us to inspect for
+   * notifications (missing `id`) before forwarding or deciding whether to absorb 4xx
+   * responses, while also enabling re-streaming the body to upstream.
+   */
+  private handleRequest(req: http.IncomingMessage, res: http.ServerResponse): void {
+    const chunks: Buffer[] = [];
+    req.on("data", (chunk: Buffer) => chunks.push(chunk));
+    req.on("error", (err) => {
+      sendJsonRpcError(res, 400, `MCP proxy request error: ${err.message}`);
+    });
+    req.on("end", () => {
+      this.forwardRequest(req, res, Buffer.concat(chunks));
+    });
+  }
+
+  private listen(port: number): Promise<number> {
+    return new Promise((resolve, reject) => {
+      const server = http.createServer((req, res) => this.handleRequest(req, res));
+      server.keepAliveTimeout = 0;
+      server.headersTimeout = 0;
+      server.requestTimeout = 0;
+      server.once("error", reject);
+      server.listen(port, "127.0.0.1", () => {
+        const addr = server.address();
+        if (addr && typeof addr === "object") {
+          server.removeListener("error", reject);
+          this.server = server;
+          this.port = addr.port;
+          resolve(addr.port);
+        } else {
+          reject(new Error("MCP proxy failed to resolve a listening port"));
+        }
+      });
+    });
+  }
+
+  /**
+   * Starts the proxy on 127.0.0.1, preferring the port used on the previous run so
+   * that URLs Antigravity persisted for existing sessions keep resolving.
+   */
+  async start(): Promise<number> {
+    if (this.port !== null) return this.port;
+
+    const remembered = this.portFile ? readPortFile(this.portFile)[this.origin.origin] : undefined;
+    if (remembered !== undefined) {
+      try {
+        return await this.listen(remembered);
+      } catch {
+        // Port taken by something else; fall through to an ephemeral one.
+      }
+    }
+
+    const port = await this.listen(0);
+    if (this.portFile) writePortFile(this.portFile, this.origin.origin, port);
+    return port;
+  }
+
+  getPort(): number | null {
+    return this.port;
+  }
+
+  /**
+   * Rewrites an upstream MCP URL to route through this proxy, preserving path and query.
+   *
+   * Throws when the proxy is not listening. Returning the original URL here would
+   * silently hand Antigravity a direct upstream connection with no header
+   * normalization, which is exactly the failure this class exists to prevent.
+   */
+  rewriteUrl(originalUrl: string): string {
+    if (this.port === null) {
+      throw new Error(
+        `MCP proxy for ${this.origin.origin} is not running; refusing to expose an un-normalized MCP URL`,
+      );
+    }
+    const target = new URL(originalUrl);
+    return `http://127.0.0.1:${this.port}${target.pathname}${target.search}`;
+  }
+
+  async stop(): Promise<void> {
+    if (!this.server) return;
+    const server = this.server;
+    this.server = null;
+    this.port = null;
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  }
+}
+
+/**
+ * Process-wide pool of proxies keyed by upstream origin.
+ *
+ * Proxies deliberately outlive individual agent connections: Antigravity writes the
+ * rewritten URL into its session database, so tearing a proxy down when one stream
+ * ends would leave every resumed session pointing at a dead port.
+ */
+export class McpProxyPool {
+  private readonly proxies = new Map<string, Promise<McpProxy>>();
+  private readonly options: McpProxyOptions;
+
+  constructor(options: McpProxyOptions = {}) {
+    this.options = options;
+  }
+
+  async rewriteUrl(originalUrl: string): Promise<string> {
+    const origin = new URL(originalUrl).origin;
+    let pending = this.proxies.get(origin);
+    if (!pending) {
+      pending = (async () => {
+        const proxy = new McpProxy(origin, this.options);
+        await proxy.start();
+        return proxy;
+      })();
+      this.proxies.set(origin, pending);
+      pending.catch(() => this.proxies.delete(origin));
+    }
+    return (await pending).rewriteUrl(originalUrl);
+  }
+
+  async stopAll(): Promise<void> {
+    const pending = Array.from(this.proxies.values());
+    this.proxies.clear();
+    await Promise.all(
+      pending.map((p) =>
+        p.then(
+          (proxy) => proxy.stop(),
+          () => undefined,
+        ),
+      ),
+    );
+  }
+}
+
+/** Shared pool. One proxy per upstream origin for the lifetime of the daemon process. */
+export const sharedMcpProxyPool = new McpProxyPool();

package/server/provider.test.ts

@@ -0,0 +1,11 @@
+import { describe, expect, it } from "vitest";
+import { createAntigravityProvider } from "./provider.js";
+
+describe("createAntigravityProvider", () => {
+  it("initializes provider registration with correct metadata", () => {
+    const provider = createAntigravityProvider();
+    expect(provider.id).toBe("antigravity");
+    expect(provider.label).toBe("Antigravity");
+    expect(typeof provider.connect).toBe("function");
+  });
+});

package/server/provider.ts

@@ -0,0 +1,37 @@
+import { runAcpProvider } from "@getpaseo/plugin/server/acp";
+import type {
+  ProviderConnectRequest,
+  ProviderConnection,
+  ProviderRegistration,
+} from "@getpaseo/plugin/server/provider";
+import { createAntigravityConnector } from "./connector.js";
+import { SteeringConnection } from "./steering.js";
+
+/**
+ * Creates the Antigravity provider registration for Paseo.
+ *
+ * Uses `createAntigravityConnector` to launch and stream to the local `agy_acp_server`,
+ * filtering redundant mode controls, discovering and advertising skills, and expanding
+ * slash commands. Wraps the established connection with `SteeringConnection` to support
+ * mid-turn steering (`prompt.steer`).
+ */
+export function createAntigravityProvider(): ProviderRegistration {
+  const baseProvider = runAcpProvider({
+    id: "antigravity",
+    label: "Antigravity",
+    description: "Connect Paseo to Google Antigravity via ACP",
+    icon: "assets/icon.svg",
+    connector: createAntigravityConnector(),
+    acpOptions: {
+      waitForInitialCommands: true,
+    },
+  });
+
+  return {
+    ...baseProvider,
+    async connect(request: ProviderConnectRequest): Promise<ProviderConnection> {
+      const connection = await baseProvider.connect(request);
+      return new SteeringConnection(connection, request);
+    },
+  };
+}

package/server/sanitize.test.ts

@@ -0,0 +1,174 @@
+import { describe, expect, it } from "vitest";
+import {
+  formatSteeringPrompt,
+  formatSystemContext,
+  sanitizeAssistantText,
+  StreamSanitizer,
+  stripSteeringPrefix,
+  stripSystemContext,
+} from "./sanitize.js";
+
+describe("sanitize", () => {
+  it("normalizes <kbd> tags into backtick code spans", () => {
+    const raw = "Press <kbd>Cmd</kbd> + <kbd>C</kbd> to copy.";
+    expect(sanitizeAssistantText(raw)).toBe("Press `Cmd` + `C` to copy.");
+  });
+
+  it("normalizes <u>, <mark>, and <sup> tags", () => {
+    const raw = "This is <u>important</u>, <mark>highlighted</mark>, and x<sup>2</sup>.";
+    expect(sanitizeAssistantText(raw)).toBe("This is *important*, **highlighted**, and x^(2).");
+  });
+
+  it("converts common LaTeX math escapes into clean Unicode characters", () => {
+    const raw = "State A $\\to$ State B, where x $\\le$ 10 and y $\\ge$ 5 (x $\\neq$ y).";
+    expect(sanitizeAssistantText(raw)).toBe("State A → State B, where x ≤ 10 and y ≥ 5 (x ≠ y).");
+  });
+
+  it("strips leaked <system_message> blocks", () => {
+    const raw = `<SYSTEM_MESSAGE>
+The subagent 81628bf1 has reported success.
+</SYSTEM_MESSAGE>
+
+We have received the first completion.`;
+    expect(sanitizeAssistantText(raw).trim()).toBe("We have received the first completion.");
+  });
+
+  it("strips preamble with <SYSTEM_MESSAGE>", () => {
+    const raw = `The following is a <SYSTEM_MESSAGE> not actually sent by the user. It is provided by the system as important information to pay attention to.
+
+<SYSTEM_MESSAGE>
+[Message] task completed
+</SYSTEM_MESSAGE>Done with task.`;
+    expect(sanitizeAssistantText(raw).trim()).toBe("Done with task.");
+  });
+
+  it("strips leaked <system_notification>, <context>, and <messaging>", () => {
+    const raw = `<system_notification>Task exited 0</system_notification><context>Context info</context>Here is your result.`;
+    expect(sanitizeAssistantText(raw).trim()).toBe("Here is your result.");
+  });
+
+  it("strips <task_notification> blocks and streaming unclosed tags", () => {
+    const raw = `<task_notification>
+Task 528dc461-72a0-4c97-a5d5-d24b66eb6d6c/task-957 ended with status: EXITED.
+Exit code: 0
+Execution time: 42.66 seconds.
+Tail output:
+Running tests
+</task_notification>`;
+    expect(sanitizeAssistantText(raw)).toBe("");
+
+    const streaming = `<task_notification>
+Task task-957 ended with status: EXITED.`;
+    expect(sanitizeAssistantText(streaming)).toBe("");
+  });
+
+  it("strips cancellation error messages emitted during turn abort / steering", () => {
+    expect(sanitizeAssistantText("The request was cancelled by the client.")).toBe("");
+    expect(sanitizeAssistantText("The request was canceled by the client")).toBe("");
+    expect(sanitizeAssistantText("context canceled.")).toBe("");
+    expect(sanitizeAssistantText("context cancelled")).toBe("");
+  });
+
+  it("strips leaked [Mid-turn update]: prefixes from assistant output", () => {
+    const raw = "[Mid-turn update]: I am stopping that action and proceeding with tests.";
+    expect(sanitizeAssistantText(raw)).toBe("I am stopping that action and proceeding with tests.");
+  });
+
+  it("strips <RECEIVE_NOTIFICATIONS_DIRECTLY> blocks and directives", () => {
+    const raw = `The diagnostic check was launched in the background to inspect the provider environment.
+
+<RECEIVE_NOTIFICATIONS_DIRECTLY>
+Wait for the notification when the diagnostic check completes.
+</RECEIVE_NOTIFICATIONS_DIRECTLY>`;
+    expect(sanitizeAssistantText(raw).trim()).toBe(
+      "The diagnostic check was launched in the background to inspect the provider environment.",
+    );
+  });
+
+  it("formats system context with system prompt and formatting guidance", () => {
+    const context = formatSystemContext("Act as an expert SRE.");
+    expect(context).toContain("[System Context]:\nAct as an expert SRE.");
+    expect(context).toContain("[Formatting Guidance]:");
+    expect(context).toContain("Math: The UI does not render LaTeX");
+    expect(context).toContain("Mermaid: Always wrap both node labels AND edge labels");
+  });
+
+  it("marks the steering replacement prompt as a mid-turn interruption", () => {
+    // Paseo answers a steer by cancelling the turn and re-dispatching the text. The
+    // marker is what tells the model the new text supersedes the instruction in flight.
+    expect(formatSteeringPrompt("STOP!")).toBe("[Mid-turn update]: STOP!");
+    expect(formatSteeringPrompt("  why port 3000?  ")).toBe("[Mid-turn update]: why port 3000?");
+  });
+
+  it("round-trips the steering marker back out of text that is about to be displayed", () => {
+    const sent = formatSteeringPrompt("use vitest");
+    expect(stripSteeringPrefix(sent).trim()).toBe("use vitest");
+    expect(sanitizeAssistantText(`Sure.\n${sent}`)).toBe("Sure.use vitest");
+  });
+  describe("stripSystemContext", () => {
+    it("strips formatted system context with custom prompt and formatting guidance", () => {
+      const context = formatSystemContext("Act as an expert SRE.");
+      const fullPrompt = `${context}\n\nDeploy the application to staging.`;
+      expect(stripSystemContext(fullPrompt)).toBe("Deploy the application to staging.");
+    });
+
+    it("strips formatting guidance when no system prompt was provided", () => {
+      const context = formatSystemContext(undefined);
+      const fullPrompt = `${context}\n\nWhat is the status?`;
+      expect(stripSystemContext(fullPrompt)).toBe("What is the status?");
+    });
+
+    it("leaves regular user prompt untouched", () => {
+      const raw = "How do I configure nginx?";
+      expect(stripSystemContext(raw)).toBe("How do I configure nginx?");
+    });
+
+    it("strips entire string when text contains only system context and formatting guidance", () => {
+      const context = formatSystemContext("Act as an expert SRE.");
+      expect(stripSystemContext(context)).toBe("");
+    });
+  });
+
+  describe("StreamSanitizer", () => {
+    it("preserves spaces between normal streamed chunks without trimming", () => {
+      const sanitizer = new StreamSanitizer();
+      expect(sanitizer.process("Hello ")).toBe("Hello ");
+      expect(sanitizer.process("world! ")).toBe("world! ");
+      expect(sanitizer.process("How are you?")).toBe("How are you?");
+    });
+
+    it("suppresses <task_notification> split across multiple streaming chunks", () => {
+      const sanitizer = new StreamSanitizer();
+      expect(sanitizer.process("Before test.\n<task_")).toBe("Before test.\n");
+      expect(sanitizer.process("notification>\nTask 123 ended.\nExit code: 0\n")).toBe("");
+      expect(sanitizer.process("Tail output:\nRunning tests...\n</task_")).toBe("");
+      expect(sanitizer.process("notification>\nAfter test.")).toBe("\nAfter test.");
+    });
+
+    it("suppresses unclosed <task_notification> streaming to the end of turn", () => {
+      const sanitizer = new StreamSanitizer();
+      expect(sanitizer.process("Start\n<task_notification>\nTask 456 running...")).toBe("Start\n");
+      expect(sanitizer.process("\nMore task output...")).toBe("");
+      expect(sanitizer.flush()).toBe("");
+    });
+
+    it("does not suppress or break mathematical < or HTML-like templates", () => {
+      const sanitizer = new StreamSanitizer();
+      expect(sanitizer.process("if a < b and c > d: ")).toBe("if a < b and c > d: ");
+      expect(sanitizer.process("std::vector<int> numbers;")).toBe("std::vector<int> numbers;");
+      expect(sanitizer.flush()).toBe("");
+    });
+
+    it("suppresses preamble <SYSTEM_MESSAGE> banners across streaming chunks", () => {
+      const sanitizer = new StreamSanitizer();
+      expect(
+        sanitizer.process(
+          "OK.\nThe following is a <SYSTEM_MESSAGE> not actually sent by the user.\n<SYSTEM_MESSAGE>",
+        ),
+      ).toBe("OK.\n");
+      expect(sanitizer.process("[Message] Internal note\n</SYSTEM_MESSAGE>\nReady!")).toBe(
+        "\nReady!",
+      );
+    });
+  });
+});