paseo-acp-agy 1.2.15 → 1.3.0

package/README.md

@@ -92,24 +92,29 @@ To include `paseo-acp-agy` in Paseo's built-in provider store (`ACP_PROVIDER_CAT
 
 ## Plan Usage & Context Window Meter Setup
 
-To display the **Google Antigravity** quota breakdown in Paseo's `Settings -> Usage` (Plan usage) and activate the real-time context-window meter ("bolinha") in the chat composer:
+### Recommended (Paseo >= 0.11.0): Official Update-Proof Paseo Plugin
 
-```bash
-npx -y paseo-acp-agy setup
-```
+Install the bundled **`antigravity-telemetry`** Paseo plugin once. It registers in `~/.paseo/config.json` and survives all future `Paseo.app`, Web, iPhone, and CLI updates without modifying signed `.app` bundles:
 
-Or if installed globally:
 ```bash
-paseo-acp-agy setup
+paseo plugin install "$(paseo-acp-agy --plugin-path)"
 ```
 
-Then restart your Paseo app or daemon:
+What this provides across Desktop, Web, and Mobile (iPhone):
+- Native **Google Antigravity** quota gauges in Paseo's Sidebar and `Settings -> Usage` (`5h` window, weekly pool, credits)
+- Live per-agent **Composer Pill** (`$cost · ctx X% · 5h Y%`) with interactive Popover / Mobile Bottom Sheet
+- Dedicated **Antigravity Telemetry** workspace panel, Command Center action, and `/agy-telemetry` slash command
+- Combined with native ACP `usage_update` notifications so Paseo's built-in `ContextWindowMeter` ("bolinha") stays deterministic on every session open, resume, model switch, and turn completion
+
+### Standalone Server Patch (Optional, Linux / Paseo < 0.11.0)
+
+For standalone `@getpaseo/cli` servers where you prefer direct server-level patching:
+
 ```bash
+paseo-acp-agy setup
 paseo daemon restart
 ```
 
-> **Note**: `paseo-acp-agy` also checks and auto-configures your local Paseo server automatically whenever it launches via `--acp`. Running `setup` manually ensures your existing daemon instance picks up the telemetry hooks immediately upon restart.
-
 ---
 
 ## Requirements

package/dist/acp-server.d.ts

@@ -10,6 +10,9 @@ export declare class ACPServer extends EventEmitter {
     private skipNarration;
     private rl;
     private isRunning;
+    private pendingRequests;
+    private usagePublishTimers;
+    private nextRequestId;
     constructor(options?: {
         input?: Readable;
         output?: Writable;
@@ -22,8 +25,17 @@ export declare class ACPServer extends EventEmitter {
     private sendNotification;
     private sendSuccess;
     private sendError;
+    sendRequest<T = any>(method: string, params: unknown): Promise<T>;
     private publishCommands;
     private publishUsageUpdate;
+    private clearUsagePublishTimers;
+    /**
+     * Schedules coalesced, unref'd usage_update notifications so ACP hosts (like Paseo)
+     * deterministically receive context window & session telemetry:
+     * - after awaiting newSession/loadSession + applyConfiguredOverrides() + session.subscribe()
+     * - after turn_completed overwrites or initializes currentTurnUsage in Paseo 0.10..0.13+
+     */
+    private scheduleUsagePublishBurst;
     private sessionState;
     private requireSession;
     private validateModel;

package/dist/acp-server.js

@@ -6,7 +6,7 @@ import { SessionManager } from "./session.js";
 import { executeSlashCommand, AVAILABLE_SLASH_COMMANDS } from "./slash-commands.js";
 import { getShortVersion } from "./version.js";
 import { resolveDefaultAgyBinary } from "./antigravity-process.js";
-import { loadConversationTranscript } from "./transcript.js";
+import { loadConversationTranscript, estimateReplayContextTokens } from "./transcript.js";
 import { normalizeToolCall, normalizeToolResult, extractPlanEntries } from "./tool-formatter.js";
 import { McpBridge } from "./mcp-bridge.js";
 function splitModelAndEffort(modelInput) {
@@ -29,6 +29,9 @@ export class ACPServer extends EventEmitter {
     skipNarration;
     rl = null;
     isRunning = false;
+    pendingRequests = new Map();
+    usagePublishTimers = new Map();
+    nextRequestId = 1;
     constructor(options = {}) {
         super();
         this.input = options.input || process.stdin;
@@ -98,6 +101,13 @@ export class ACPServer extends EventEmitter {
         };
         this.send(response);
     }
+    sendRequest(method, params) {
+        return new Promise((resolve, reject) => {
+            const id = this.nextRequestId++;
+            this.pendingRequests.set(id, { resolve, reject });
+            this.send({ jsonrpc: "2.0", id, method, params });
+        });
+    }
     publishCommands(sessionId) {
         this.sendNotification(ACP_METHODS.SESSION_UPDATE, {
             sessionId,
@@ -129,6 +139,53 @@ export class ACPServer extends EventEmitter {
             },
         });
     }
+    clearUsagePublishTimers(sessionId) {
+        if (sessionId !== undefined) {
+            const timers = this.usagePublishTimers.get(sessionId);
+            if (timers) {
+                for (const t of timers)
+                    clearTimeout(t);
+                this.usagePublishTimers.delete(sessionId);
+            }
+            return;
+        }
+        for (const timers of this.usagePublishTimers.values()) {
+            for (const t of timers)
+                clearTimeout(t);
+        }
+        this.usagePublishTimers.clear();
+    }
+    /**
+     * Schedules coalesced, unref'd usage_update notifications so ACP hosts (like Paseo)
+     * deterministically receive context window & session telemetry:
+     * - after awaiting newSession/loadSession + applyConfiguredOverrides() + session.subscribe()
+     * - after turn_completed overwrites or initializes currentTurnUsage in Paseo 0.10..0.13+
+     */
+    scheduleUsagePublishBurst(sessionId, delaysMs) {
+        this.clearUsagePublishTimers(sessionId);
+        if (!this.isRunning || delaysMs.length === 0)
+            return;
+        const timers = new Set();
+        this.usagePublishTimers.set(sessionId, timers);
+        for (const delayMs of delaysMs) {
+            const timer = setTimeout(() => {
+                timers.delete(timer);
+                if (timers.size === 0) {
+                    this.usagePublishTimers.delete(sessionId);
+                }
+                if (!this.isRunning)
+                    return;
+                const current = this.sessionManager.getSession(sessionId);
+                if (current) {
+                    this.publishUsageUpdate(current);
+                }
+            }, delayMs);
+            if (typeof timer.unref === "function") {
+                timer.unref();
+            }
+            timers.add(timer);
+        }
+    }
     async sessionState(session, forceModels = false) {
         const availableModels = await fetchAvailableModels(this.binaryPath, forceModels);
         return {
@@ -198,6 +255,20 @@ export class ACPServer extends EventEmitter {
         const isNotification = id === undefined || id === null;
         const params = (parsed.params || {});
         logger.debug("Received ACP message", { method, isNotification, id });
+        // Handle responses to requests initiated by the server (e.g. session/request_permission)
+        if (id !== undefined && !method) {
+            const pending = this.pendingRequests.get(id);
+            if (pending) {
+                this.pendingRequests.delete(id);
+                if (parsed.error) {
+                    pending.reject(parsed.error);
+                }
+                else {
+                    pending.resolve(parsed.result);
+                }
+                return;
+            }
+        }
         try {
             switch (method) {
                 case ACP_METHODS.INITIALIZE: {
@@ -242,17 +313,9 @@ export class ACPServer extends EventEmitter {
                         this.sendSuccess(id, await this.sessionState(session, true));
                         this.publishCommands(session.id);
                         this.publishUsageUpdate(session);
-                        // Re-publish usage after ACPAgent completes awaiting newSession and stores this.sessionId
-                        setTimeout(() => {
-                            if (this.sessionManager.getSession(session.id)) {
-                                this.publishUsageUpdate(session);
-                            }
-                        }, 150);
-                        setTimeout(() => {
-                            if (this.sessionManager.getSession(session.id)) {
-                                this.publishUsageUpdate(session);
-                            }
-                        }, 500);
+                        // Re-publish usage across startup window so ACPAgent receives it after
+                        // awaiting newSession + applyConfiguredOverrides() + session.subscribe()
+                        this.scheduleUsagePublishBurst(session.id, [120, 450, 1200, 2800]);
                     }
                     break;
                 }
@@ -288,6 +351,9 @@ export class ACPServer extends EventEmitter {
                                         session.setTitle(firstUser.text.slice(0, 80).replace(/\r?\n/g, " ").trim());
                                     }
                                 }
+                                if (replayItems.length > 0) {
+                                    session.seedEstimatedContextUsage(estimateReplayContextTokens(replayItems));
+                                }
                                 for (const item of replayItems) {
                                     switch (item.type) {
                                         case "user_message":
@@ -355,12 +421,7 @@ export class ACPServer extends EventEmitter {
                             this.sendSuccess(id, await this.sessionState(session));
                             this.publishCommands(session.id);
                             this.publishUsageUpdate(session);
-                            const activeSession = session;
-                            setTimeout(() => {
-                                if (this.sessionManager.getSession(activeSession.id)) {
-                                    this.publishUsageUpdate(activeSession);
-                                }
-                            }, 150);
+                            this.scheduleUsagePublishBurst(session.id, [120, 450, 1200, 2800]);
                         }
                     }
                     catch (err) {
@@ -391,10 +452,23 @@ export class ACPServer extends EventEmitter {
                             created = true;
                         }
                         await session.ensureReadyForResume();
+                        const resumeConversationId = session.process.currentConversationId;
+                        if (resumeConversationId &&
+                            session.usage.contextWindowUsedTokens === 0 &&
+                            session.usage.totalTokens === 0) {
+                            try {
+                                const replayItems = await loadConversationTranscript(resumeConversationId);
+                                if (replayItems.length > 0) {
+                                    session.seedEstimatedContextUsage(estimateReplayContextTokens(replayItems));
+                                }
+                            }
+                            catch { }
+                        }
                         if (!isNotification) {
                             this.sendSuccess(id, await this.sessionState(session));
                             this.publishCommands(session.id);
                             this.publishUsageUpdate(session);
+                            this.scheduleUsagePublishBurst(session.id, [120, 450, 1200, 2800]);
                         }
                     }
                     catch (err) {
@@ -435,6 +509,17 @@ export class ACPServer extends EventEmitter {
                         mode: sourceSession?.mode,
                         permission: sourceSession?.permission,
                         conversationId: sourceSession?.process.currentConversationId,
+                        usage: sourceSession
+                            ? {
+                                inputTokens: 0,
+                                outputTokens: 0,
+                                cachedInputTokens: 0,
+                                totalTokens: 0,
+                                totalCostUsd: 0,
+                                contextWindowUsedTokens: sourceSession.usage.contextWindowUsedTokens,
+                                contextWindowMaxTokens: sourceSession.usage.contextWindowMaxTokens,
+                            }
+                            : undefined,
                         binaryPath: this.binaryPath,
                     });
                     if (sourceSession?.title) {
@@ -444,6 +529,7 @@ export class ACPServer extends EventEmitter {
                         this.sendSuccess(id, await this.sessionState(newSession));
                         this.publishCommands(newSession.id);
                         this.publishUsageUpdate(newSession);
+                        this.scheduleUsagePublishBurst(newSession.id, [120, 450, 1200]);
                     }
                     break;
                 }
@@ -494,8 +580,11 @@ export class ACPServer extends EventEmitter {
                                     },
                                 });
                             }
-                            if (!isNotification)
+                            this.publishUsageUpdate(session);
+                            if (!isNotification) {
                                 this.sendSuccess(id, { stopReason: "end_turn" });
+                                this.scheduleUsagePublishBurst(session.id, [25, 150]);
+                            }
                             break;
                         }
                         let hasSentNonNarration = false;
@@ -559,13 +648,70 @@ export class ACPServer extends EventEmitter {
                                             rawInput: toolCall.rawInput,
                                         },
                                     });
-                                    if (toolCall.questionCard) {
-                                        this.sendNotification(ACP_METHODS.SESSION_UPDATE, {
+                                    if (toolName === "ask_question") {
+                                        const rawParams = step.tool_info.parameters || {};
+                                        const rawQuestions = Array.isArray(rawParams.questions)
+                                            ? rawParams.questions
+                                            : [];
+                                        const options = [];
+                                        for (let qIdx = 0; qIdx < rawQuestions.length; qIdx++) {
+                                            const q = rawQuestions[qIdx];
+                                            const opts = Array.isArray(q.options) ? q.options : [];
+                                            for (let optIdx = 0; optIdx < opts.length; optIdx++) {
+                                                const opt = opts[optIdx];
+                                                const clean = typeof opt === "string" ? opt.replace(/^\(Recommended\)\s*/i, "").trim() : String(opt);
+                                                const isRec = typeof opt === "string" && (opt.includes("(Recommended)") || opt.includes("(Recomendado)"));
+                                                options.push({
+                                                    optionId: `q${qIdx + 1}_opt${optIdx + 1}`,
+                                                    name: `${clean}${isRec ? " (Recomendado)" : ""}`,
+                                                    kind: "allow_once",
+                                                });
+                                            }
+                                        }
+                                        options.push({
+                                            optionId: "cancel",
+                                            name: "Cancelar",
+                                            kind: "reject_once",
+                                        });
+                                        const promptText = rawQuestions.map((q) => q.question).filter(Boolean).join(" / ") || "Pergunta do Assistente";
+                                        this.sendRequest("session/request_permission", {
                                             sessionId: session.id,
-                                            update: {
-                                                sessionUpdate: "agent_message_chunk",
-                                                content: { type: "text", text: `\n\n${toolCall.questionCard}\n\n` },
+                                            toolCall: {
+                                                toolCallId: toolCall.toolCallId,
+                                                title: toolCall.title,
+                                                kind: "question",
+                                                content: [{ type: "text", text: promptText }],
+                                                rawInput: toolCall.rawInput,
                                             },
+                                            options,
+                                            questions: rawQuestions,
+                                        }).then((permRes) => {
+                                            logger.info("Interactive question answered in Paseo", { permRes });
+                                            const outcome = permRes?.outcome;
+                                            let answerText = "";
+                                            if (outcome?._meta?.answers && typeof outcome._meta.answers === "object") {
+                                                answerText = Object.entries(outcome._meta.answers)
+                                                    .map(([k, v]) => `• **${k}**: ${v}`)
+                                                    .join("\n");
+                                            }
+                                            else if (outcome?.optionId && outcome.optionId !== "cancel") {
+                                                const matched = options.find((o) => o.optionId === outcome.optionId);
+                                                answerText = matched ? matched.name : outcome.optionId;
+                                            }
+                                            if (answerText) {
+                                                this.sendNotification(ACP_METHODS.SESSION_UPDATE, {
+                                                    sessionId: session.id,
+                                                    update: {
+                                                        sessionUpdate: "agent_message_chunk",
+                                                        content: {
+                                                            type: "text",
+                                                            text: `\n\n> 💡 **Opção Selecionada:**\n${answerText}\n\n`,
+                                                        },
+                                                    },
+                                                });
+                                            }
+                                        }).catch((err) => {
+                                            logger.debug("Interactive question cancelled or dismissed", { error: err.message });
                                         });
                                     }
                                 }
@@ -674,6 +820,7 @@ export class ACPServer extends EventEmitter {
                             if (session.isCancelled) {
                                 if (!isNotification) {
                                     this.sendSuccess(id, { stopReason: "cancelled", usage: usagePayload });
+                                    this.scheduleUsagePublishBurst(session.id, [25, 150]);
                                 }
                             }
                             else if (resultEvent.result?.status === "ERROR") {
@@ -688,10 +835,12 @@ export class ACPServer extends EventEmitter {
                                 });
                                 if (!isNotification) {
                                     this.sendSuccess(id, { stopReason: "refusal", usage: usagePayload });
+                                    this.scheduleUsagePublishBurst(session.id, [25, 150]);
                                 }
                             }
                             else if (!isNotification) {
                                 this.sendSuccess(id, { stopReason: "end_turn", usage: usagePayload });
+                                this.scheduleUsagePublishBurst(session.id, [25, 150]);
                             }
                         }
                         catch (promptErr) {
@@ -699,8 +848,10 @@ export class ACPServer extends EventEmitter {
                             if (session.isCancelled ||
                                 errorMsg.includes("cancelled") ||
                                 errorMsg.includes("Turn was cancelled")) {
-                                if (!isNotification)
+                                if (!isNotification) {
                                     this.sendSuccess(id, { stopReason: "cancelled" });
+                                    this.scheduleUsagePublishBurst(session.id, [25, 150]);
+                                }
                             }
                             else {
                                 logger.error("Error executing prompt turn", { error: errorMsg, sessionId });
@@ -711,8 +862,10 @@ export class ACPServer extends EventEmitter {
                                         content: { type: "text", text: `\n\n**Error:** ${errorMsg}\n` },
                                     },
                                 });
-                                if (!isNotification)
+                                if (!isNotification) {
                                     this.sendSuccess(id, { stopReason: "refusal" });
+                                    this.scheduleUsagePublishBurst(session.id, [25, 150]);
+                                }
                             }
                         }
                     }
@@ -736,6 +889,7 @@ export class ACPServer extends EventEmitter {
                 case ACP_METHODS.SESSION_CLOSE:
                 case ACP_METHODS.SESSION_CLOSE_ALIAS: {
                     const sessionId = String(params.sessionId || "");
+                    this.clearUsagePublishTimers(sessionId);
                     await this.sessionManager.closeSession(sessionId);
                     if (!isNotification)
                         this.sendSuccess(id, {});
@@ -758,8 +912,11 @@ export class ACPServer extends EventEmitter {
                         break;
                     }
                     session.setMode(modeId);
-                    if (!isNotification)
+                    if (!isNotification) {
                         this.sendSuccess(id, {});
+                        this.publishUsageUpdate(session);
+                        this.scheduleUsagePublishBurst(session.id, [80, 350, 1000]);
+                    }
                     break;
                 }
                 case ACP_METHODS.SESSION_SET_MODEL:
@@ -801,8 +958,11 @@ export class ACPServer extends EventEmitter {
                         currentPermission: session.permission,
                         availableModels: models,
                     });
-                    if (!isNotification)
+                    if (!isNotification) {
                         this.sendSuccess(id, { configOptions });
+                        this.publishUsageUpdate(session);
+                        this.scheduleUsagePublishBurst(session.id, [80, 350, 1000]);
+                    }
                     break;
                 }
                 case ACP_METHODS.SESSION_SET_CONFIG_OPTION:
@@ -869,8 +1029,11 @@ export class ACPServer extends EventEmitter {
                         currentPermission: session.permission,
                         availableModels: models,
                     });
-                    if (!isNotification)
+                    if (!isNotification) {
                         this.sendSuccess(id, { configOptions });
+                        this.publishUsageUpdate(session);
+                        this.scheduleUsagePublishBurst(session.id, [80, 350, 1000]);
+                    }
                     break;
                 }
                 case "provider/usage":
@@ -897,6 +1060,7 @@ export class ACPServer extends EventEmitter {
         if (!this.isRunning)
             return;
         this.isRunning = false;
+        this.clearUsagePublishTimers();
         if (this.rl) {
             this.rl.close();
             this.rl = null;

package/dist/antigravity-process.js

@@ -135,9 +135,20 @@ export function resolveDefaultAgyBinary(force = false) {
                 }
             }
             else {
-                const localPath = path.join(home, ".local", "bin", "agy");
-                if (fs.existsSync(localPath))
-                    resolved = localPath;
+                const posixCandidates = [
+                    path.join(home, ".local", "bin", "agy"),
+                    "/opt/homebrew/bin/agy",
+                    "/usr/local/bin/agy",
+                    "/usr/bin/agy",
+                    path.join(home, ".antigravity", "bin", "agy"),
+                    path.join(home, ".gemini", "antigravity-cli", "bin", "agy"),
+                ];
+                for (const cand of posixCandidates) {
+                    if (fs.existsSync(cand)) {
+                        resolved = cand;
+                        break;
+                    }
+                }
             }
         }
     }

package/dist/asar.d.ts

@@ -21,6 +21,11 @@ export declare function readArchiveHeader(archivePath: string): {
  * Lists all file paths inside an ASAR archive.
  */
 export declare function listPackage(archivePath: string): string[];
+/**
+ * Reads a single UTF-8 text file directly from an ASAR archive without extracting
+ * the entire archive to disk. Returns null if the archive or entry cannot be read.
+ */
+export declare function readFileFromPackage(archivePath: string, relPath: string): string | null;
 /**
  * Pure TypeScript, zero-dependency ASAR archive extractor.
  * Compatible with all Node.js versions (Node 18, 20, 22, 24+) across Windows, macOS, and Linux.

package/dist/asar.js

@@ -54,6 +54,40 @@ export function listPackage(archivePath) {
     walk(header, "");
     return result;
 }
+/**
+ * Reads a single UTF-8 text file directly from an ASAR archive without extracting
+ * the entire archive to disk. Returns null if the archive or entry cannot be read.
+ */
+export function readFileFromPackage(archivePath, relPath) {
+    try {
+        const { header, dataBaseOffset } = readArchiveHeader(archivePath);
+        const parts = relPath.replace(/^\/+/, "").split("/").filter(Boolean);
+        let node = header;
+        for (const part of parts) {
+            node = node?.files?.[part];
+            if (!node)
+                return null;
+        }
+        if (node.unpacked || node.size === undefined || node.offset === undefined) {
+            return null;
+        }
+        if (node.size === 0)
+            return "";
+        const fileOffset = dataBaseOffset + parseInt(node.offset, 10);
+        const fd = fs.openSync(archivePath, "r");
+        try {
+            const buf = Buffer.alloc(node.size);
+            const bytesRead = fs.readSync(fd, buf, 0, node.size, fileOffset);
+            return buf.subarray(0, bytesRead).toString("utf8");
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Pure TypeScript, zero-dependency ASAR archive extractor.
  * Compatible with all Node.js versions (Node 18, 20, 22, 24+) across Windows, macOS, and Linux.

package/dist/index.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { execFileSync } from "node:child_process";
 import { ACPServer } from "./acp-server.js";
 import { logger } from "./logger.js";
@@ -8,6 +10,11 @@ import { ensurePaseoIntegration, restorePaseoIntegration, findPaseoServerInstall
 import { resolveDefaultAgyBinary, isWindowsBatchScript } from "./antigravity-process.js";
 import { parseAgyQuotaOutput } from "./protocol.js";
 const args = process.argv.slice(2);
+const bundledPluginDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "paseo-plugin");
+if (args.includes("plugin-path") || args.includes("--plugin-path")) {
+    process.stdout.write(`${bundledPluginDir}\n`);
+    process.exit(0);
+}
 if (args.includes("--version") || args.includes("-v")) {
     if (args.includes("--json")) {
         process.stdout.write(JSON.stringify(resolveBuildMetadata(), null, 2) + "\n");
@@ -31,12 +38,14 @@ Commands:
   setup, patch   Configure and integrate Antigravity telemetry with Paseo
   doctor         Diagnose Antigravity binary, quota provider, and Paseo status
   restore        Restore original Paseo files from backup (.bak)
+  plugin-path    Print path to the update-proof Paseo telemetry plugin directory
 
 Options:
   --acp             Start ACP server over stdio (default)
   --setup           Integrate Antigravity with local Paseo server installation
   --doctor          Run environment, binary, and telemetry diagnostics
   --restore         Restore original Paseo files from backup
+  --plugin-path     Print bundled Paseo plugin directory for 'paseo plugin install'
   --force-macos-app Force patching inside macOS .app bundle (re-signs with ad-hoc)
   --skip-naration   Drop leading narration-only assistant chunks (e.g. 'I will...')
   --skip-narration  Alias for --skip-naration
@@ -139,6 +148,22 @@ if (args.includes("doctor") || args.includes("--doctor")) {
     process.stdout.write("\n3. Paseo Installation Targets:\n");
     const serverPaths = findPaseoServerInstallations();
     const asarPaths = findPaseoAsarPaths();
+    let telemetryPluginEnabled = false;
+    try {
+        const paseoHome = process.env.PASEO_HOME || path.join(process.env.HOME || process.env.USERPROFILE || "", ".paseo");
+        const cfgPath = path.join(paseoHome, "config.json");
+        if (fs.existsSync(cfgPath)) {
+            const cfg = JSON.parse(fs.readFileSync(cfgPath, "utf-8"));
+            if (cfg?.pluginsEnabled === true && cfg?.plugins) {
+                const p = cfg.plugins["antigravity-telemetry"];
+                if (p && p.enabled !== false) {
+                    telemetryPluginEnabled = true;
+                }
+            }
+        }
+    }
+    catch { }
+    process.stdout.write(`  - [Plugin] antigravity-telemetry -> ${telemetryPluginEnabled ? "[ENABLED]" : "[NOT INSTALLED]"}\n`);
     const totalFound = serverPaths.length + asarPaths.length;
     if (totalFound === 0) {
         process.stdout.write("  [!] No Paseo server or desktop installations discovered in standard paths.\n");
@@ -185,21 +210,22 @@ if (args.includes("doctor") || args.includes("--doctor")) {
         process.stdout.write("  - Antigravity CLI ('agy') executable was not found.\n");
         process.stdout.write("    Action: Install Antigravity CLI or set AGY_BIN_PATH environment variable.\n");
     }
-    if (totalFound === 0) {
+    if (totalFound === 0 && !telemetryPluginEnabled) {
         hasIssue = true;
         process.stdout.write("  - No Paseo installations found.\n");
         process.stdout.write("    Action: Set PASEO_SERVER_PATH or PASEO_ASAR_PATH to your Paseo install directory if located elsewhere.\n");
     }
-    else if (unpatchedCount > 0) {
+    else if (unpatchedCount > 0 && !telemetryPluginEnabled) {
         hasIssue = true;
-        if (paseoRunning) {
-            process.stdout.write(`  - Found ${unpatchedCount} unpatched Paseo target(s), but Paseo is currently running.\n`);
-            process.stdout.write("    Action: Close Paseo completely (Stop-Process -Name \"Paseo\" -Force), then run:\n");
+        process.stdout.write(`  - Found ${unpatchedCount} unpatched Paseo target(s) and 'antigravity-telemetry' plugin is not yet installed.\n`);
+        process.stdout.write("    Recommended update-proof action (survives Paseo updates without touching .app signatures):\n");
+        process.stdout.write(`      paseo plugin install "${bundledPluginDir}"\n`);
+        if (isWin) {
+            process.stdout.write("    Or to patch standalone Paseo after closing it (Stop-Process -Name \"Paseo\" -Force):\n");
             process.stdout.write("      npx -y paseo-acp-agy setup\n");
         }
         else {
-            process.stdout.write(`  - Found ${unpatchedCount} unpatched Paseo target(s).\n`);
-            process.stdout.write("    Action: Run setup to patch Paseo for Antigravity telemetry:\n");
+            process.stdout.write("    Or for standalone @getpaseo/cli servers:\n");
             process.stdout.write("      npx -y paseo-acp-agy setup\n");
         }
     }
@@ -272,8 +298,9 @@ if (args.includes("setup") ||
                 process.stdout.write(`\n🛡️  Preserved macOS Code Signature:\n` +
                     `   Skipped ${res.skippedPaths.length} target(s) inside macOS .app bundle to protect official Apple Developer ID signature\n` +
                     `   and prevent Gatekeeper "damaged app" warnings.\n` +
-                    `   (Antigravity ACP runs standalone and does not require modifying Paseo.app).\n` +
-                    `   If you specifically wish to patch the .app bundle, run with: paseo-acp-agy patch --force-macos-app\n\n`);
+                    `   Recommended update-proof telemetry setup (survives every Paseo update):\n` +
+                    `     paseo plugin install "${bundledPluginDir}"\n` +
+                    `   (Or if you specifically wish to patch the .app bundle: paseo-acp-agy patch --force-macos-app)\n\n`);
             }
             if (isPaseoRunning()) {
                 const isWin = process.platform === "win32";

package/dist/paseo-patcher.d.ts

@@ -58,7 +58,17 @@ export declare function ensurePaseoIntegration(options?: {
     forceMacosApp?: boolean;
 }): Promise<PatchResult>;
 /**
- * Restores original unpatched Paseo files from backup (.bak) archives.
+ * Reads the Paseo version embedded inside an ASAR archive's package.json.
+ */
+export declare function resolveAsarArchiveVersion(archivePath: string): string | null;
+/**
+ * Resolves the authoritative Paseo version of a target app.asar installation,
+ * preferring macOS bundle Info.plist (CFBundleShortVersionString) when inside an .app bundle.
+ */
+export declare function resolveTargetPaseoVersion(asarPath: string): string | null;
+/**
+ * Restores original unpatched Paseo files from backup (.bak) archives,
+ * enforcing strict version matching so an older backup can never downgrade a newer Paseo app.
  */
 export declare function restorePaseoIntegration(): Promise<{
     restored: string[];