agy-context-saver 0.0.0-stage → 1.2.1

package/mcp/instructions.md

@@ -0,0 +1,30 @@
+# Agy-Context-Saver MCP Server Instructions
+
+## Overview
+Agy-Context-Saver is the universal Model Context Protocol server and lifecycle governor for Google Antigravity, paired with RTK (Rust Token Killer) for transparent CLI output reduction.
+
+## Core Rules for Antigravity Agents
+1. **Reactive Wakeup (Zero Task Polling)**:
+   - When background tasks run, DO NOT call `manage_task(Action='status')` or `schedule` polling timers.
+   - Stop calling tools and yield the turn. The system notifies you automatically via `<SYSTEM_MESSAGE>`.
+   - Repeated polling triggers an escalating circuit breaker (frozen at 5 denials).
+2. **Never Read Internal State Directly**:
+   - Access to `.system_generated/` via `view_file` is strictly denied to prevent transcript explosion.
+   - Use `read_transcript` or `query_transcript` to inspect conversation history cleanly.
+3. **Platform-Aware Codebase Inspection**:
+   - **Windows**: Use `rtk read <file>`, `rtk find <path>`, and `rtk rg "<pattern>" .` (the trailing `.` is required to avoid stdin stalls).
+   - **POSIX**: Use `rtk read <file>`, `rtk ls <path>`, and `rtk grep "<pattern>"` or `rtk rg "<pattern>"`.
+
+## Available MCP Tools
+- `check_context_health`: Diagnoses transcript turn counts, byte payload, and polling loops. Accepts `transcriptPath` or `conversationId`.
+- `subagent_brief`: Generates scope-isolated instructions for delegated subagents to prevent parent context bloat.
+- `read_transcript`: Streams recent turns from `transcript.jsonl` or `transcript_full.jsonl` formatted as clean Markdown.
+- `query_transcript`: Forensic regex search and filtering engine across transcript steps with optional `summaryOnly: true`.
+- `get_installation_status`: Audits live health of the plugin link, hook, MCP server, tool schemas, and RTK.
+- `sync_installation`: Synchronizes and repairs all 4 integration layers in ~25ms.
+
+## Diagnostic & CLI Playbook
+- Audit Status: `npm run status` or `node mcp/index.js status`
+- Run Test Suite: `npm test`
+- CLI Help: `node mcp/index.js --help`
+- ⚠️ Warning: Do not run `npm start` or `node mcp/index.js` without subcommands interactively (it is a stdio JSON-RPC server).

package/mcp_config.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "agy-context-saver": {
+      "command": "node",
+      "args": ["mcp/index.js"]
+    }
+  }
+}

package/package.json

@@ -1,6 +1,42 @@
-{
-  "name": "agy-context-saver",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "agy-context-saver",
+  "version": "1.2.1",
+  "description": "Universal Model Context Protocol (MCP) server & lifecycle governor purpose-built for Google Antigravity",
+  "main": "mcp/index.js",
+  "bin": {
+    "agy-context-saver": "mcp/index.js"
+  },
+  "type": "module",
+  "scripts": {
+    "start": "node mcp/index.js",
+    "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-e2e-probes.mjs && node tests/test-performance-probes.mjs && node tests/test-installed-verification.mjs && node tests/test-lifecycle-rollback.mjs"
+  },
+  "keywords": [
+    "antigravity",
+    "mcp",
+    "model-context-protocol",
+    "gemini",
+    "context-window",
+    "lifecycle-hooks",
+    "agentic-coding"
+  ],
+  "files": [
+    "mcp",
+    "scripts",
+    "rules",
+    "skills",
+    "hooks.json",
+    "plugin.json",
+    "mcp_config.json",
+    "install.ps1",
+    "install.sh",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "author": "paragon-ux",
+  "license": "MIT"
+}

package/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "agy-context-saver",
+  "version": "1.2.1",
+  "description": "Deterministic background polling governor and subagent context preservation shield for Antigravity"
+}

package/rules/AGENTS.md

@@ -0,0 +1,78 @@
+# Antigravity Execution & Context Governance (Agy-Context-Saver + RTK)
+
+## Core Architectural Boundary
+- **RTK (Rust Token Killer)**: Owns shell command transparent rewriting, output reduction, and compact codebase inspection (`rtk read`, `rtk grep`, `rtk find`, `rtk ls`, `rtk err`, `rtk summary`).
+- **Agy-Context-Saver**: Owns Antigravity lifecycle governance, Reactive Wakeup enforcement, transcript forensics, and session integrity.
+
+---
+
+## Layer 1: Background Tasks & Polling Ban (Reactive Wakeup SSOT)
+- **Zero-Tolerance on Task Polling**: Do NOT call `manage_task(Action='status')` or `schedule` timers in a loop to wait for running background tasks. Background tasks execute asynchronously and automatically resume the agent via **Reactive Wakeup** (`<SYSTEM_MESSAGE>`).
+- **Yield Turn Immediately**: When a process moves to the background, stop calling tools, output a concise status message, and yield the turn.
+- **No Keyword or Timer Exemptions**: Words like "debug", "timeout", "diagnose", or "stuck" do NOT exempt an agent from lifecycle governance. Timers with `duration >= 120` are NOT exempt.
+- **Circuit Breaker**: Repeated polling calls across any tasks in a session trigger an escalating circuit breaker. At 5 cumulative denials, autonomous execution is frozen via `force_ask`.
+
+---
+
+## Layer 2: Transparent Shell Execution & Codebase Inspection via RTK
+- **Native Shell Commands**: Run shell commands normally using `run_command`. The PreToolUse hook transparently rewrites supported commands via RTK (`git`, `pytest`, `cargo`, `npm`, etc.) to produce ultra-compact outputs.
+- **Canonical Codebase Inspection**: Native file and search inspection tools (`view_file`, `grep_search`, `find_by_name`, `list_dir`) that bypass RTK are blocked for workspace files. Use RTK's canonical CLI interfaces via `run_command`:
+  - `rtk read <file>`: Read file with intelligent token filtering and line ranges.
+  - `rtk find <path>`: Compact file search tree and directory listings (cross-platform, works on Windows & POSIX).
+  - Search commands by platform:
+    - **Windows**: Use `rtk rg "<pattern>" .` (explicit target `.` is required to prevent stdin pipe hanging) or `rg "<pattern>" .`.
+    - **POSIX / Linux / macOS**: Use `rtk grep "<pattern>"` or `rtk rg "<pattern>"`.
+  - Directory listing by platform:
+    - **Windows**: Use `rtk find <path>` or PowerShell `dir` / `Get-ChildItem`. (Avoid `rtk ls` or `rtk tree` on Windows as they rely on POSIX binaries/flags).
+    - **POSIX / Linux / macOS**: Use `rtk ls <path>` or `rtk tree`.
+  - `rtk err <cmd>`: Run command and show only errors/warnings.
+  - `rtk summary <cmd>`: Run command and produce a 2-line heuristic summary.
+- **Antigravity Special Files Safe Harbor**: Documented Antigravity special files (`SKILL.md`, brain artifacts, `.gemini/config/` configs) are permitted via `view_file`.
+- **Protected Internal State**: Direct native inspection of `.system_generated/` (transcripts, task logs, progress files) is strictly forbidden. Use Agy MCP tools `read_transcript` and `query_transcript`.
+
+---
+
+## Layer 3: Synchronous Execution & Subagent Delegation
+- **Maximum Synchronous Window**: Non-daemon `run_command` calls are automatically set to `WaitMsBeforeAsync: 10000` to complete synchronously and prevent unnecessary background detachment.
+- **Targeted Test Execution**: Avoid massive multi-minute test sweeps in interactive turns. Run targeted, quiet, fail-fast commands (e.g. `pytest tests/test_core.py -q -x`).
+- **Subagent Delegation**: Delegate heavy multi-file exploration and exploratory research to subagents (`invoke_subagent`). Subagents absorb intermediate steps and return high-signal summaries.
+- **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
+When an agent or developer tests this framework, follow this exact sequence without guessing:
+
+1. **Verify Live Registration & Health (Fast, non-blocking)**:
+   ```bash
+   npm run status
+   # or
+   node mcp/index.js status
+   ```
+   *Expected*: Reports `HEALTHY & ACTIVE 🛡️` across plugin link, hook, MCP config, schemas, and RTK.
+
+2. **Execute Full Automated Test Suite**:
+   ```bash
+   npm test
+   ```
+   *Expected*: All 5 test suites pass (Hook unit tests, MCP protocol tests, E2E probes, live system validation, lifecycle rollback).
+
+3. **Verify Individual Layers On-Demand**:
+   - Governance Hook: `node tests/test-hook.mjs`
+   - MCP Protocol & JSON-RPC: `node tests/test-mcp.mjs`
+   - E2E Probes: `node tests/test-e2e-probes.mjs`
+   - Live System Checks: `node tests/test-installed-verification.mjs`
+   - Lifecycle & Rollback: `node tests/test-lifecycle-rollback.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": ["..."] }`.
+
+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.
+   - ❌ **Do NOT run `manage_task(Action='status')` loops**: Status polling is governed; 5 polls trigger the `force_ask` circuit breaker.
+   - ❌ **Do NOT run `npm run uninstall` as an isolated test**: It strips the live hook from `~/.gemini/config/`. If run, immediately re-run `npm run setup`.
+   - ❌ **Do NOT omit explicit target paths with `rtk rg`**: Always provide a path (e.g. `rtk rg "pattern" .`) to prevent stdin blocking.