agy-context-saver 0.0.0-stage → 1.2.1

package/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to `Agy-Context-Saver` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.2.1] - 2026-10-07
+
+### Documentation & Developer Experience
+- **MCP Prompts Documentation**: Formally documented the `/mcp:agy-context-saver:context_shield` prompt across `README.md` and the documentation site, clarifying the operational difference between user slash commands (Prompts) and autonomous agent capabilities (Tools).
+- **Quickstart Optimization**: Repositioned the Quickstart installation block to the very top of `README.md` and `docs/index.md` for immediate onboarding.
+- **Zensical Docs Site Overhaul**: Added `context_shield` reference and tip callouts across `docs/index.md`, `docs/tools.md`, and `docs/governance.md`; updated navigation title to `Tools & Prompts`.
+- **Dynamic Test Assertions**: Updated installed MCP server verification test to dynamically synchronize with `package.json` version.
+
+---
+
+## [1.2.0] - 2026-10-07
+
+### Performance & Forensics
+- **Batch Full-Transcript Dereferencing**: Replaced sequential full-transcript scans with `batchFindFullSteps()`, reducing $N$-item dereferencing from $O(N)$ full-file passes down to a single streaming pass ($O(1)$) in 18.4ms.
+- **Sliding-Window Turn Retention**: Bounded transcript memory retention in `read_transcript` (`WINDOW_SIZE = Math.max(100, lastTurns * 15)`) with an early-stopping block formatter, parsing 2,000 steps in 21.8ms under 24 KB memory.
+- **Regex LRU Caching**: Added in-memory LRU cache (`regexCache`, capacity: 100) for query pattern compilation in `query_transcript`.
+- **Short-Circuit Field Search**: Converted transcript search to test fields sequentially (`content` $\to$ `thinking` $\to$ `tool_calls`), avoiding heavy string concatenations.
+- **Fast-Path Message Cleaning**: Added fast-path bypass in `cleanMessageContent` for strings $\le 120$ characters, eliminating redundant base64 regexes and newline splits.
+- **Static Rules In-Memory Cache**: Cached `rules/AGENTS.md` in memory with `mtimeMs` file stat invalidation, eliminating disk I/O on `resources/read` and `prompts/get`.
+
+### Execution Governor & Hook
+- **Fast-Path Builtin Bypass**: Added `NON_REWRITABLE_BINARIES` set (`node`, `powershell`, `pwsh`, `cmd`, `dir`, `echo`, `cd`, `del`, etc.) and PowerShell cmdlet prefixes to bypass `spawnSync("rtk")`, dropping execution latency from ~30ms to $< 0.05$ms.
+- **Persistent Command Rewrite LRU Cache**: Implemented persistent disk LRU cache (`agy-rtk-rewrite-cache.json` in `os.tmpdir()`) for rewritable commands, reducing repeat rewrite lookups to $< 0.1$ms.
+- **Session Ledger State Partitioning**: Partitioned session state by conversation ID (`agy-session-${safeId}.json`) to eliminate cross-session file contention.
+
+### Registration & Lifecycle
+- **Idempotent Config & Schema Synchronization**: Added `safeWriteFileIfChanged` and `safeCopyFileIfChanged` across all configuration (`hooks.json`, `mcp_config.json`) and MCP tool schemas (`~/.gemini/antigravity/mcp/agy-context-saver/`), eliminating disk churn during repeat syncs.
+- **RTK Provisioning Check Reuse**: Passed pre-detected RTK metadata to `ensureRtkInstalled()` to eliminate redundant `execSync` version checks during installation.
+
+### Security & Reliability
+- **Stdio Payload Safety Ceiling**: Added 10 MB payload guard (`MAX_STDIO_PAYLOAD_BYTES`) on the MCP stdio line reader, emitting standard JSON-RPC `-32600 Invalid Request` on oversized payloads.
+- **New Performance Verification Suite**: Added `tests/test-performance-probes.mjs` verifying batch dereferencing, sliding window bounds, stdio safety ceiling, and idempotent writes.
+
+---
+
+## [1.1.0] - 2026-10-07
+
+### Added
+- **Closed Execution Topology & Governance Invariants**: Comprehensive PreToolUse hook intercepting native inspection tools (`view_file`, `grep_search`, `list_dir`, `find_by_name`) and hard-routing them to RTK.
+- **Root-Based Antigravity State Protection**: Denied direct access to `.system_generated/` internal files to prevent transcript bloat and loop degradation.
+- **Session-Wide Lifecycle Ledger**: Non-resettable session task polling counter with Tier 3 `force_ask` circuit breaker at 5 denials.
+- **Evaluator & Benchmark Mutation Safeguard**: Gated mutation of evaluator or benchmark artifacts behind user confirmation.
+- **Platform-Aware Windows Routing**: Windows-native routing for `rtk rg "<pattern>" .` and `rtk find <path>` to eliminate stdin hangs.
+- **Universal MCP Server**: 6 core tools (`check_context_health`, `subagent_brief`, `get_installation_status`, `sync_installation`, `read_transcript`, `query_transcript`).
+
+---
+
+## [1.0.0] - 2026-10-07
+
+### Initial Release
+- Initial release of Agy-Context-Saver.
+- Antigravity Model Context Protocol (MCP) server.
+- Background task lifecycle governance and reactive wakeup enforcement.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 paragon-ux
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,173 @@
-# Temporary Holding Version
+# Agy-Context-Saver 🛡️
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Model Context Protocol (MCP) Server & Lifecycle Governor for Google Antigravity (Powered by RTK)**
+
+[![npm version](https://img.shields.io/npm/v/agy-context-saver.svg)](https://www.npmjs.com/package/agy-context-saver)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-Zensical-purple.svg)](https://paragon-ux.github.io/agy-context-saver/)
+[![Tests](https://img.shields.io/badge/tests-100%25%20passing-brightgreen.svg)](https://github.com/paragon-ux/agy-context-saver/actions)
+
+`Agy-Context-Saver` is a high-performance lifecycle governor and zero-dependency MCP server purpose-built for **Google Antigravity** (`agy`), paired with **RTK (Rust Token Killer)** for transparent CLI output reduction.
+
+It permanently eliminates session degradation, memory bloat, and context window exhaustion caused by **background task busy-wait polling**, **uncompressed terminal outputs**, and **raw JSON transcript reading**.
+
+---
+
+## Quickstart (Instant Install)
+
+Install and synchronize the governor and RTK across your Antigravity environment:
+
+```bash
+# Fastest: one-line registration via npx
+npx agy-context-saver install
+
+# Or locally from this repository
+npm run setup
+
+# Audit health across all layers at any time
+npm run status
+```
+
+---
+
+## Architectural Division of Responsibilities
+
+```text
+                         Antigravity Agent
+                                |
+             +------------------+------------------+
+             |                                     |
+        run_command                         native inspection /
+             |                              lifecycle tools
+             v                                     |
+        RTK hook                                    |
+             |                             +---------+----------+
+             v                             |                    |
+        RTK execution                  inspection tools      lifecycle
+             |                             |                    |
+             v                             v                    v
+     compact command output          Agy DENY + route      Agy governance
+                                           |                    |
+                                           v                    v
+                                      RTK read/grep/find     Agy MCP
+                                           |                    |
+                                           +---------+----------+
+                                                     |
+                                                     v
+                                              useful context
+```
+
+### RTK Owns:
+- Transparent `run_command` rewriting (`rtk rewrite`)
+- Shell command output reduction (`git`, `pytest`, `cargo`, `npm`, `docker`, etc.)
+- Canonical codebase inspection CLI (`rtk read`, `rtk grep`, `rtk find`, `rtk ls`, `rtk tree`)
+- Focused diagnostic utilities (`rtk err`, `rtk summary`)
+
+### Agy Owns:
+- Antigravity lifecycle management & Reactive Wakeup enforcement
+- Background task polling governance & 5-strike circuit breaker
+- Antigravity internal state protection (`.system_generated/`)
+- Zero-JSON Markdown transcript extraction (`read_transcript`, `query_transcript`)
+- Subagent delegation formulation (`subagent_brief`)
+- Benchmark and evaluation artifact mutation protection
+
+---
+
+## The Core Problems Solved
+
+1. **The Polling Trap**: When shell tasks detach to background jobs (`task-XYZ`), agents waste tokens repeatedly polling `manage_task(Action='status')` or scheduling artificial timers. Agy enforces native **Reactive Wakeup** (`<SYSTEM_MESSAGE>`).
+2. **The Terminal Bloat Trap**: Routine test runs and git operations dump hundreds of lines of noise into context. RTK compresses these outputs natively before they enter model context.
+3. **The Raw Transcript Trap**: Reading `transcript.jsonl` dumps megabytes of raw JSON into context. Agy blocks direct reads of `.system_generated` and provides high-density Markdown streaming tools.
+4. **Native Inspection Bypass**: Native inspection tools (`view_file`, `grep_search`, `find_by_name`, `list_dir`) bypass token reduction. Agy hard-routes workspace inspection to RTK's canonical CLI (`rtk read`, `rtk grep`, `rtk find`, `rtk ls`).
+
+---
+
+## Key Capabilities
+
+- **Transparent RTK Rewriting**: Native `run_command` calls are automatically rewritten (e.g. `pytest` $\to$ `rtk pytest`) via Antigravity PreToolUse hooks.
+- **Canonical Codebase Inspection**:
+  - `rtk read <file>`: Read file with intelligent token filtering and line ranges.
+  - `rtk find <path>`: Compact file search tree and directory listing (cross-platform, works on Windows & POSIX).
+  - Search by platform:
+    - **Windows**: `rtk rg "<pattern>" .` (explicit target `.` prevents child process stdin stalls) or `rg "<pattern>" .`.
+    - **POSIX / Linux / macOS**: `rtk grep "<pattern>"` or `rtk rg "<pattern>"`.
+  - Directory listing by platform:
+    - **Windows**: `rtk find <path>` or PowerShell `dir` / `Get-ChildItem`. (Avoid `rtk ls` / `rtk tree` on Windows as they rely on POSIX binaries/flags).
+    - **POSIX / Linux / macOS**: `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**: Direct `view_file` access to `SKILL.md`, brain artifacts, and config files is preserved.
+- **Protected Internal State**: Root-based guard prevents reading `.system_generated/` (transcripts, task logs, progress).
+- **Session-Wide Lifecycle Ledger**: Polling checks are tracked globally per session; changing task IDs or waiting does not reset governance.
+- **Zero-JSON Transcript Streaming**: Stream conversation turns without raw JSON syntax using `read_transcript` and `query_transcript`.
+
+---
+
+## Zero-Guesswork Testing & Verification Playbook
+
+To cleanly test every layer of the framework without guesswork or interactive stalls:
+
+### 1. Audit Live Registration
+```bash
+npm run status
+# or
+node mcp/index.js status
+```
+*Confirms that all 4 integration layers (Plugin link, Lifecycle Hook, MCP Server, Schemas) and RTK are active.*
+
+### 2. Run Complete Automated Test Suite
+```bash
+npm test
+```
+*Runs all 5 test suites (28 hook tests, MCP protocol tests, E2E probes, installed verification, lifecycle rollback).*
+
+### 3. Run Targeted Tests Individually
+```bash
+# Governance hook unit tests (28 closed-topology tests)
+node tests/test-hook.mjs
+
+# MCP server protocol & method tests
+node tests/test-mcp.mjs
+
+# End-to-end edge case & probe tests
+node tests/test-e2e-probes.mjs
+
+# Live installed environment verification
+node tests/test-installed-verification.mjs
+
+# Clean install/uninstall/restore lifecycle test
+node tests/test-lifecycle-rollback.mjs
+```
+
+### 4. Test MCP Tools from Antigravity Agent
+- `get_installation_status`: Call with `{}` to audit all 4 layers + RTK.
+- `check_context_health`: Call with `{ "transcriptPath": "<path-to-transcript.jsonl>" }`.
+- `read_transcript`: Call with `{ "conversationId": "<uuid>", "lastTurns": 3, "mode": "compact" }`.
+- `query_transcript`: Call with `{ "conversationId": "<uuid>", "query": "<term>", "summaryOnly": true }`.
+- `subagent_brief`: Call with `{ "objective": "<goal>", "scopeFiles": ["..."] }`.
+
+### 5. Testing Pitfalls & Anti-Patterns to Avoid
+- ❌ **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 loop on `manage_task(Action='status')`**: Polling triggers the session ledger circuit breaker at 5 cumulative denials. Rely on native Reactive Wakeup (`<SYSTEM_MESSAGE>`).
+- ❌ **Do NOT run `npm run uninstall` as a standalone check**: It unregisters the live hook. If run, immediately re-run `npm run setup`.
+- ❌ **On Windows, do NOT omit the directory in `rtk rg`**: Always run `rtk rg "<pattern>" .` to avoid stdin pipe blocking.
+
+---
+
+## MCP Tools & Slash Commands
+
+* **User Slash Command (`/mcp:...`)**:
+  - `/mcp:agy-context-saver:context_shield`: Injects 3-layer governance rules and RTK standards into any session with one click. *(MCP Prompts appear in your chat autocomplete menu; MCP Tools are called autonomously by the agent).*
+* **Agent MCP Tools**:
+  1. `check_context_health`: Diagnoses conversation transcript turn budgets, payload size, RTK status, and polling loops.
+  2. `subagent_brief`: Formulates scope-isolated prompts for delegated subagents.
+  3. `read_transcript`: Reads recent conversation history in clean Markdown format (compact/full).
+  4. `query_transcript`: Forensic filtering and regex search engine for conversation logs.
+  5. `get_installation_status`: Inspects live Antigravity plugin link, hook, MCP server, tool schemas, and RTK binary.
+  6. `sync_installation`: Re-verifies and repairs all integration layers in ~25ms.
+
+---
+
+## License
+
+MIT License. Copyright (c) 2026 paragon-ux.

package/hooks.json

@@ -0,0 +1,16 @@
+{
+  "agy-context-saver": {
+    "PreToolUse": [
+      {
+        "matcher": "manage_task|run_command|schedule",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node scripts/execution-guard-hook.mjs",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/install.ps1

@@ -0,0 +1,42 @@
+# Agy-Context-Saver Universal Installer for Windows
+# Installs hook script, wrapper, and registers in ~/.gemini/config/hooks.json & mcp_config.json
+
+$ErrorActionPreference = "Stop"
+
+$GeminiConfigDir = [System.IO.Path]::Combine($env:USERPROFILE, ".gemini", "config")
+$DestHook = [System.IO.Path]::Combine($GeminiConfigDir, "scripts", "execution-guard-hook.mjs")
+
+# 1. Ensure ~/.gemini/config exists
+if (-not (Test-Path $GeminiConfigDir)) {
+    New-Item -ItemType Directory -Path $GeminiConfigDir -Force | Out-Null
+}
+
+# 2. Create node.cmd wrapper in ~/.gemini/config (prevents Windows cmd quote issues)
+$NodeCmdPath = [System.IO.Path]::Combine($GeminiConfigDir, "node.cmd")
+$NodeCmdLines = @(
+    '@echo off',
+    'setlocal',
+    'set "ARGS=%*"',
+    '',
+    'echo %ARGS% | findstr /i "execution-guard" >nul',
+    'if %errorlevel% equ 0 (',
+    "    `"C:\Program Files\nodejs\node.exe`" `"$DestHook`"",
+    '    exit /b %errorlevel%',
+    ')',
+    '',
+    'echo %ARGS% | findstr /i "waymark" >nul',
+    'if %errorlevel% equ 0 (',
+    '    "C:\Program Files\nodejs\node.exe" "%USERPROFILE%\Desktop\Frameworks\Deepseek-Project\Waymark\scripts\hooks\waymark-compact-hook.mjs"',
+    '    exit /b %errorlevel%',
+    ')',
+    '',
+    'echo {"decision": "allow"}',
+    'exit /b 0'
+)
+$NodeCmdContent = $NodeCmdLines -join "`r`n"
+Set-Content -Path $NodeCmdPath -Value $NodeCmdContent -Encoding ASCII
+Write-Host "[OK] Node wrapper installed to: $NodeCmdPath" -ForegroundColor Green
+
+# 3. Run cross-platform registration engine
+$RegisterScript = [System.IO.Path]::Combine($PSScriptRoot, "scripts", "install-register.mjs")
+& node "$RegisterScript"

package/install.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+# Agy-Context-Saver Zero-Delay Installer for macOS & Linux
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+node "$SCRIPT_DIR/scripts/install-register.mjs" "$@"