agy-context-saver 1.5.0 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agy-context-saver",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Universal Model Context Protocol (MCP) server & lifecycle governor purpose-built for Google Antigravity",
   "main": "mcp/index.js",
   "bin": {
@@ -12,7 +12,22 @@
     "setup": "node scripts/install-register.mjs",
     "uninstall": "node scripts/install-register.mjs --uninstall",
     "status": "node scripts/install-register.mjs --status",
-    "test": "node tests/test-hook.mjs && node tests/test-mcp.mjs && node tests/test-output-governance.mjs && node tests/test-e2e-probes.mjs && node tests/test-performance-probes.mjs && node tests/test-installed-verification.mjs && node tests/test-lifecycle-rollback.mjs"
+    "preflight": "node scripts/release-preflight.mjs",
+    "test": "node tests/test-hook.mjs && node tests/test-mcp.mjs && node tests/test-output-governance.mjs && node tests/test-e2e-probes.mjs && node tests/test-performance-probes.mjs && node tests/test-installed-verification.mjs && node tests/test-lifecycle-rollback.mjs && node tests/test-subagent-trials.mjs && node tests/test-check-only-readonly.mjs && node tests/test-malformed-config-preservation.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/paragon-ux/Agy-Context-Saver.git"
+  },
+  "homepage": "https://paragon-ux.github.io/agy-context-saver/",
+  "bugs": {
+    "url": "https://github.com/paragon-ux/Agy-Context-Saver/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
   },
   "keywords": [
     "antigravity",
@@ -24,6 +39,7 @@
     "agentic-coding"
   ],
   "files": [
+    "assets",
     "mcp",
     "scripts",
     "rules",

package/plugin.json

@@ -1,5 +1,12 @@
 {
   "name": "agy-context-saver",
-  "version": "1.5.0",
-  "description": "Deterministic background polling governor and subagent context preservation shield for Antigravity"
+  "displayName": "Antigravity Context Shield & Governor",
+  "version": "1.6.0",
+  "description": "Deterministic background polling governor, RTK terminal optimizer, and subagent context preservation shield for Antigravity.",
+  "logo": "assets/logo.svg",
+  "suggestedPrompts": [
+    "Audit context health and token consumption for this session",
+    "Formulate an isolated subagent brief under Pointer-Over-Wire protocol",
+    "Inspect recent conversation turns without raw JSON transcript bloat"
+  ]
 }

package/rules/AGENTS.md

@@ -55,12 +55,14 @@
   - **Fail-Fast Flags are Opt-In**: Fail-fast flags (`-x`, `--maxfail=1`) are opt-in. Use them when quickly debugging a localized failure, but omit them when assessing the full blast radius across the codebase to avoid the "whack-a-mole" loop.
   - **Coordinated Watchdog Mandatory for Full Sweeps**: When running full multi-minute test sweeps without `-x`, agents **MUST** pair execution with the **Coordinated Watchdog Protocol** (`schedule(DurationSeconds=45, ...)`) and output a **Pre-Yield Status Card**. Never yield silently.
   - **Subagent Delegation for Deep Audits**: When a comprehensive repository-wide test audit is required, delegate the sweep to a subagent (`invoke_subagent`) to keep the main thread responsive.
-- **Subagent Delegation**: Delegate heavy multi-file exploration and exploratory research to subagents (`invoke_subagent`). Subagents absorb intermediate steps and return high-signal summaries.
+- **Subagent Delegation & Pointer-Over-Wire (POW)**:
+  - Delegate heavy multi-file exploration, deep research, and repo sweeps to subagents (`invoke_subagent`). Subagents absorb intermediate steps and return high-signal summaries.
+  - **POW Protocol**: Payloads or deliverables exceeding 1 KB must be written to workspace scratch files (e.g. `scratch/<task>_findings.md` or artifacts). Transmit **ONLY** an Executive Summary (3–5 sentences), a Scoreboard / Verdict table, and a clickable file link (`file:///...`) in `send_message` to prevent transport truncation and parent context bloat.
 - **Benchmark / Evaluator Integrity**: Never mutate benchmark definitions, prompt templates, or scoring artifacts during an active evaluation without explicit user confirmation.
 
 ---
 
-## Layer 4: Zero-Guesswork Testing & Verification Playbook
+## Appendix: Zero-Guesswork Testing & Verification Playbook
 When an agent or developer tests this framework, follow this exact sequence without guessing:
 
 1. **Verify Live Registration & Health (Fast, non-blocking)**:
@@ -75,21 +77,24 @@ When an agent or developer tests this framework, follow this exact sequence with
    ```bash
    npm test
    ```
-   *Expected*: All 5 test suites pass (Hook unit tests, MCP protocol tests, E2E probes, live system validation, lifecycle rollback).
+   *Expected*: All 8 test suites pass (Hook unit tests, MCP protocol tests, output governance, E2E probes, performance probes, live system validation, lifecycle rollback, subagent trials).
 
 3. **Verify Individual Layers On-Demand**:
    - Governance Hook: `node tests/test-hook.mjs`
    - MCP Protocol & JSON-RPC: `node tests/test-mcp.mjs`
+   - Output Governance: `node tests/test-output-governance.mjs`
    - E2E Probes: `node tests/test-e2e-probes.mjs`
+   - Performance Probes: `node tests/test-performance-probes.mjs`
    - Live System Checks: `node tests/test-installed-verification.mjs`
    - Lifecycle & Rollback: `node tests/test-lifecycle-rollback.mjs`
+   - Subagent Delegation Trials: `node tests/test-subagent-trials.mjs`
 
 4. **Verify MCP Tools in Antigravity**:
    - `get_installation_status`: Inspect live integration layers.
    - `check_context_health`: Pass `{ "transcriptPath": "<path-to-transcript.jsonl>" }`.
    - `read_transcript`: Pass `{ "conversationId": "<uuid>", "lastTurns": 3, "mode": "compact" }`.
    - `query_transcript`: Pass `{ "conversationId": "<uuid>", "query": "<pattern>", "summaryOnly": true }`.
-   - `subagent_brief`: Pass `{ "objective": "<goal>", "scopeFiles": ["..."] }`.
+   - `subagent_brief`: Pass `{ "objective": "<goal>", "role": "<role>", "scopeFiles": ["..."] }` or pass multiple via `{ "subagents": [...] }` to generate ready-to-use `invoke_subagent` JSON payloads.
 
 5. **Operational Anti-Patterns (What NOT to do)**:
    - ❌ **Do NOT run `npm start` or `node mcp/index.js` interactively**: It starts the stdio JSON-RPC daemon and waits indefinitely on stdin.

package/scripts/execution-guard-hook.mjs

@@ -32,6 +32,7 @@ import os from "node:os";
 import path from "node:path";
 import process from "node:process";
 import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
 
 function respond(obj) {
   process.stdout.write(JSON.stringify(obj) + "\n");
@@ -207,8 +208,12 @@ function getTaskLogMatch(text) {
 const TASK_TAIL_BYTES = 262144; // transcript tail scanned first (256 KB)
 const TASK_QUIET_MS = 300000;   // log-mtime fallback: quiet for 5 min => treated as finished
 
+function getProfileHomeDir() {
+  return process.env.AGY_TEST_PROFILE_DIR || os.homedir();
+}
+
 function getBrainDir() {
-  return process.env.AGY_BRAIN_DIR || path.join(os.homedir(), ".gemini", "antigravity", "brain");
+  return process.env.AGY_BRAIN_DIR || path.join(getProfileHomeDir(), ".gemini", "antigravity", "brain");
 }
 
 /** Reads the last `bytes` of a file. Returns { text, whole } or null. */
@@ -280,19 +285,54 @@ function getTaskState(match, convId) {
   return "UNKNOWN";
 }
 
-/**
- * Runs `rtk rewrite <cmd>`. Spawns the PATH binary directly (a separate `--version` probe doubled
- * the cost of every cache miss); falls back to the plugin-local binary only when PATH has none.
- */
-function runRtkRewrite(cmd) {
-  const opts = { encoding: "utf-8", timeout: 2000, windowsHide: true };
-  const res = spawnSync("rtk", ["rewrite", cmd], opts);
-  if (res.error && res.error.code === "ENOENT") {
-    const exeName = os.platform() === "win32" ? "rtk.exe" : "rtk";
-    const pluginBin = path.join(os.homedir(), ".gemini", "config", "plugins", "agy-context-saver", "bin", exeName);
-    if (fs.existsSync(pluginBin)) return spawnSync(pluginBin, ["rewrite", cmd], opts);
+function isCompatibleRtkVersion(versionStr) {
+  if (!versionStr || typeof versionStr !== "string") return false;
+  const match = versionStr.match(/(\d+)\.(\d+)\.(\d+)/);
+  if (!match) return false;
+  const major = parseInt(match[1], 10);
+  const minor = parseInt(match[2], 10);
+  return major === 0 && (minor === 50 || minor === 51);
+}
+
+function getLocalRtkCandidate() {
+  const names = os.platform() === "win32" ? ["rtk.exe", "rtk.cmd"] : ["rtk"];
+  const hookDir = path.dirname(fileURLToPath(import.meta.url));
+  for (const exeName of names) {
+    const pluginBin = path.join(getProfileHomeDir(), ".gemini", "config", "plugins", "agy-context-saver", "bin", exeName);
+    if (fs.existsSync(pluginBin)) return pluginBin;
+  }
+  for (const exeName of names) {
+    const repoBin = path.resolve(hookDir, "..", "bin", exeName);
+    if (fs.existsSync(repoBin)) return repoBin;
+  }
+  return "";
+}
+
+function findFirstRtkOnPath() {
+  const pathEnv = process.env.PATH || process.env.Path || "";
+  const dirs = pathEnv.split(path.delimiter).filter(Boolean);
+  const exts = os.platform() === "win32" ? [".exe", ".cmd", ".bat"] : [""];
+  for (const dir of dirs) {
+    for (const ext of exts) {
+      const candidate = path.join(dir, `rtk${ext}`);
+      try {
+        if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+          return candidate;
+        }
+      } catch {}
+    }
   }
-  return res;
+  return "";
+}
+
+function spawnRtk(bin, args, opts) {
+  if (!bin) return { error: Object.assign(new Error("ENOENT"), { code: "ENOENT" }), status: null, stdout: "", stderr: "" };
+  if (os.platform() === "win32" && /\.(cmd|bat)$/i.test(bin)) {
+    const quotedBin = /\s/.test(bin) ? `"${bin}"` : bin;
+    const quotedArgs = args.map((a) => (/\s|["&|<>^]/.test(a) ? `"${a.replace(/"/g, '\\"')}"` : a)).join(" ");
+    return spawnSync("cmd.exe", ["/d", "/s", "/c", `"${quotedBin} ${quotedArgs}"`], { ...opts, windowsVerbatimArguments: true });
+  }
+  return spawnSync(bin, args, opts);
 }
 
 const NON_REWRITABLE_BINARIES = new Set([
@@ -332,18 +372,77 @@ function loadRewriteCache() {
   return inMemoryRewriteCache;
 }
 
+function resolveCompatibleRtk() {
+  const localCandidate = getLocalRtkCandidate();
+  const pathCandidate = findFirstRtkOnPath();
+  const envSig = `${pathCandidate}::${localCandidate}`;
+  const cache = loadRewriteCache();
+  if (cache.__envSig === envSig && cache.__rtkResolved !== undefined) {
+    return cache.__rtkResolved;
+  }
+
+  for (const k of Object.keys(cache)) delete cache[k];
+
+  const opts = { encoding: "utf-8", timeout: 2000, windowsHide: true };
+  let resolved = null;
+
+  const pathRes = pathCandidate ? spawnRtk(pathCandidate, ["--version"], opts) : { status: 1, stdout: "" };
+  const pathCompatible = !pathRes.error && pathRes.status === 0 && isCompatibleRtkVersion(pathRes.stdout);
+
+  if (pathCompatible) {
+    resolved = { exe: pathCandidate, prefix: "rtk" };
+  } else if (localCandidate) {
+    const localRes = spawnRtk(localCandidate, ["--version"], opts);
+    const localCompatible = !localRes.error && localRes.status === 0 && isCompatibleRtkVersion(localRes.stdout);
+    if (localCompatible) {
+      const normalizedLocal = localCandidate.replace(/\\/g, "/");
+      const prefix = /\s/.test(normalizedLocal) ? `"${normalizedLocal}"` : normalizedLocal;
+      resolved = { exe: localCandidate, prefix };
+    }
+  }
+
+  cache.__envSig = envSig;
+  cache.__rtkResolved = resolved;
+  try {
+    const tmp = `${REWRITE_CACHE_FILE}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(cache), "utf-8");
+    try {
+      fs.renameSync(tmp, REWRITE_CACHE_FILE);
+    } catch {
+      fs.writeFileSync(REWRITE_CACHE_FILE, JSON.stringify(cache), "utf-8");
+      try { fs.unlinkSync(tmp); } catch {}
+    }
+  } catch {}
+
+  return resolved;
+}
+
+function runRtkRewrite(cmd, resolvedRtk) {
+  const rtk = resolvedRtk || resolveCompatibleRtk();
+  if (!rtk) return { status: 1, stdout: "", stderr: "No compatible RTK binary available" };
+  const opts = { encoding: "utf-8", timeout: 2000, windowsHide: true };
+  return spawnRtk(rtk.exe, ["rewrite", cmd], opts);
+}
+
 /**
  * Persists one rewrite result. Re-reads the file first so concurrent hook processes merge instead
  * of overwriting each other, trims to the newest entries, and writes atomically (temp + rename).
  */
 function rememberRewrite(cmd, rewritten) {
-  loadRewriteCache()[cmd] = rewritten;
+  const cache = loadRewriteCache();
+  cache[cmd] = rewritten;
   try {
     const disk = readRewriteCacheFile();
+    const envSig = cache.__envSig ?? disk.__envSig;
+    const rtkResolved = cache.__rtkResolved ?? disk.__rtkResolved;
+    delete disk.__envSig;
+    delete disk.__rtkResolved;
     delete disk[cmd];
     disk[cmd] = rewritten;
     const keys = Object.keys(disk);
     for (const k of keys.slice(0, Math.max(0, keys.length - REWRITE_CACHE_MAX))) delete disk[k];
+    if (envSig !== undefined) disk.__envSig = envSig;
+    if (rtkResolved !== undefined) disk.__rtkResolved = rtkResolved;
     const tmp = `${REWRITE_CACHE_FILE}.${process.pid}.tmp`;
     fs.writeFileSync(tmp, JSON.stringify(disk), "utf-8");
     try {
@@ -364,7 +463,11 @@ function rewriteCommandWithRtk(rawCmd) {
   if (!trimmed) return rawCmd;
 
   // Already prefixed with rtk
-  if (/^rtk(?:\.exe)?\s+/i.test(trimmed)) {
+  if (/^rtk(?:\.exe)?(?=\s|$)/i.test(trimmed)) {
+    const rtk = resolveCompatibleRtk();
+    if (rtk && rtk.prefix !== "rtk") {
+      return trimmed.replace(/^rtk(?:\.exe)?(?=\s|$)/i, rtk.prefix);
+    }
     return trimmed;
   }
 
@@ -382,7 +485,7 @@ function rewriteCommandWithRtk(rawCmd) {
     return trimmed;
   }
 
-    // Fast-path bypass for shell builtins, non-rewritable binaries, and powershell cmdlets
+  // Fast-path bypass for shell builtins, non-rewritable binaries, and powershell cmdlets
   const firstWord = (trimmed.match(/^[^\s"']+/)?.[0] || "").toLowerCase();
   if (
     NON_REWRITABLE_BINARIES.has(firstWord) ||
@@ -397,6 +500,9 @@ function rewriteCommandWithRtk(rawCmd) {
     return trimmed;
   }
 
+  const rtk = resolveCompatibleRtk();
+  if (!rtk) return trimmed;
+
   // Check persistent cache
   const cache = loadRewriteCache();
   if (cache[trimmed] !== undefined) {
@@ -406,7 +512,7 @@ function rewriteCommandWithRtk(rawCmd) {
   let rewritten = trimmed;
   let cacheable = false;
   try {
-    const res = runRtkRewrite(trimmed);
+    const res = runRtkRewrite(trimmed, rtk);
     // Never cache timeouts, spawn errors or signals: a transient failure must not pin a command
     // to "no rewrite" for the lifetime of the cache.
     cacheable = !res.error && !res.signal && typeof res.status === "number" && res.status >= 0 && res.status <= 3;
@@ -414,6 +520,9 @@ function rewriteCommandWithRtk(rawCmd) {
     // RTK exits 0 or 3 when rewritten, with new command on stdout
     if ((res.status === 0 || res.status === 3) && res.stdout && res.stdout.trim()) {
       rewritten = res.stdout.trim();
+      if (rtk.prefix !== "rtk") {
+        rewritten = rewritten.replace(/^rtk(?:\.exe)?(?=\s|$)/i, rtk.prefix);
+      }
     }
   } catch {}
 
@@ -542,7 +651,7 @@ try {
 
     const rewritten = rewriteCommandWithRtk(rawCmd);
     const effectiveCmd = rewritten;
-    const isRtkRead = /^rtk(?:\.exe)?\s+read\b/i.test(effectiveCmd);
+    const isRtkRead = /^(?:["']?[^\s"']*[/\\])?rtk(?:\.exe|\.cmd|\.bat)?["']?\s+read\b/i.test(effectiveCmd);
 
     // Check 3: Step Output Spillover Safe Harbor (rtk read only; it clamps + windows output)
     if (isSpillover && !isRtkRead) {
@@ -655,14 +764,57 @@ try {
       respond({ decision: "allow" });
     }
 
-    // 2c. Hard-Route Workspace Code/Data Inspection to Canonical RTK Commands (LH-07)
-    if (toolName === "view_file" || toolName === "read_file") {
+    // 2e. Bounded Slice Safe Harbor for view_file
+    // Allow view_file IF AND ONLY IF it is a bounded slice inspection (StartLine and EndLine <= 150 lines)
+    if (toolName === "view_file") {
+      const rawStart = args.StartLine !== undefined ? args.StartLine : args.start_line;
+      const rawEnd = args.EndLine !== undefined ? args.EndLine : args.end_line;
+      const hasSliceParams = typeof rawStart !== "undefined" || typeof rawEnd !== "undefined";
+
+      if (hasSliceParams) {
+        const startLine = Number(rawStart);
+        const endLine = Number(rawEnd);
+
+        if (
+          typeof rawStart !== "undefined" &&
+          typeof rawEnd !== "undefined" &&
+          Number.isInteger(startLine) &&
+          Number.isInteger(endLine) &&
+          startLine > 0 &&
+          endLine >= startLine
+        ) {
+          const span = endLine - startLine + 1;
+          const MAX_SAFE_SLICE_LINES = 150;
+          if (span <= MAX_SAFE_SLICE_LINES) {
+            respond({ decision: "allow" });
+          }
+          respond({
+            decision: "deny",
+            reason: `Antigravity Governance: Oversized file slice via 'view_file' (${span} lines > ${MAX_SAFE_SLICE_LINES} lines max safe window). Reduce line range or run 'rtk read ${target || "<file>"}' via run_command instead.`
+          });
+        }
+
+        respond({
+          decision: "deny",
+          reason: `Antigravity Governance: Invalid slice range via 'view_file'. Ensure StartLine and EndLine are positive integers with EndLine >= StartLine (max 150 lines), or run 'rtk read ${target || "<file>"}' via run_command instead.`
+        });
+      }
+
+      // Default when no slice attempted: keep hook identical to original behavior (zero slice advertisement)
       respond({
         decision: "deny",
         reason: `Antigravity Governance: Native file inspection via '${toolName}' bypasses token optimization. Run 'rtk read ${target || "<file>"}' via run_command instead.`
       });
     }
 
+    // 2f. Hard-Route Full-File / Other Workspace Code Inspection to Canonical RTK Commands (LH-07)
+    if (toolName === "read_file") {
+      respond({
+        decision: "deny",
+        reason: `Antigravity Governance: Native file inspection via 'read_file' bypasses token optimization. Run 'rtk read ${target || "<file>"}' via run_command instead.`
+      });
+    }
+
     if (toolName === "read_many_files") {
       respond({
         decision: "deny",
@@ -706,8 +858,8 @@ try {
   if (toolName === "manage_task") {
     const action = String(args.Action || args.action || "").replace(/^["']|["']$/g, "").trim().toLowerCase();
 
-    // kill, send_input are always allowed immediately
-    if (action !== "status" && action !== "list") {
+    // kill, send_input, and list are always allowed immediately
+    if (action !== "status") {
       respond({ decision: "allow" });
     }