paseo-acp-agy 1.2.16 → 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

@@ -11,6 +11,7 @@ export declare class ACPServer extends EventEmitter {
     private rl;
     private isRunning;
     private pendingRequests;
+    private usagePublishTimers;
     private nextRequestId;
     constructor(options?: {
         input?: Readable;
@@ -27,6 +28,14 @@ export declare class ACPServer extends EventEmitter {
     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) {
@@ -30,6 +30,7 @@ export class ACPServer extends EventEmitter {
     rl = null;
     isRunning = false;
     pendingRequests = new Map();
+    usagePublishTimers = new Map();
     nextRequestId = 1;
     constructor(options = {}) {
         super();
@@ -138,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 {
@@ -265,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;
                 }
@@ -311,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":
@@ -378,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) {
@@ -414,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) {
@@ -458,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) {
@@ -467,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;
                 }
@@ -517,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;
@@ -754,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") {
@@ -768,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) {
@@ -779,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 });
@@ -791,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]);
+                                }
                             }
                         }
                     }
@@ -816,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, {});
@@ -838,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:
@@ -881,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:
@@ -949,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":
@@ -977,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[];