kvguard 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,66 @@
-# Temporary Holding Version
-
-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.
+# kvguard
+
+[![npm](https://img.shields.io/npm/v/kvguard?color=cb3837&logo=npm)](https://www.npmjs.com/package/kvguard)
+[![PyPI](https://img.shields.io/pypi/v/kvguard?color=3775a9&logo=pypi&logoColor=white)](https://pypi.org/project/kvguard/)
+[![CI](https://github.com/tranhoangtu-it/kvguard/actions/workflows/ci.yml/badge.svg)](https://github.com/tranhoangtu-it/kvguard/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue)](https://github.com/tranhoangtu-it/kvguard#license)
+
+**Catch 1-token prompt-cache misses in real time — and heal them before the request leaves your machine.**
+
+Prompt caches (Anthropic, OpenAI) and local KV caches (llama.cpp, Ollama, vLLM) only reuse work when a new prompt starts with *exactly* the same bytes as the last one. One rotating header, one timestamp, one reshuffled MCP tool list — and 30–80K tokens are billed or prefilled again. Nothing errors. You just pay more and wait longer.
+
+kvguard is a local proxy + terminal UI that shows you **where** the prefix broke, **why**, and **what it cost** — and can rewrite requests so it doesn't break again.
+
+## Quick start
+
+```bash
+npx kvguard --heal -- claude                                   # Claude Code
+npx kvguard --heal --target http://127.0.0.1:8080 -- opencode  # any agent → llama-server
+npx kvguard attach                                             # live TUI in a second terminal
+```
+
+The first run downloads the native binary for your platform from [GitHub Releases](https://github.com/tranhoangtu-it/kvguard/releases) and verifies its SHA-256 checksum. No Docker, no database, no account.
+
+## What you see
+
+```
+ Turn  Branch / Slot    Model               Prefix Health  Hit %  Root Cause / Action
+ #04   main [slot 0]    claude-sonnet-4-5   [█░░░░░░░░░]   12%    ❌ BUST @ tok ~#418 (volatile header/id in system · system[0].text)
+ #05   main [slot 0]    claude-sonnet-4-5   [██████████]   96%    ⚡ HEALED (sorted 48 tools + stripped cch= billing header)
+ #06   sub-1 [slot 1]   claude-haiku-4-5    [··········]    –     ◆ NEW BRANCH
+```
+
+## What it catches
+
+| Cause | Typical source | `--heal` |
+|---|---|---|
+| tools[] order shuffled | MCP servers starting asynchronously | ✅ sorted by name |
+| schema key order changed | non-deterministic JSON serialization | ✅ RFC 8785 key order |
+| volatile header in system | Claude Code `cch=` billing header on non-Anthropic backends | ✅ stripped |
+| timestamp in prefix | `Current time: …` with seconds | ✅ pinned per session |
+| chat-template drift | Qwen/DeepSeek dropping `<think>` from old turns | ✅ `--normalize-think-tags` |
+| history message mutated | compaction, truncated tool output | 🔎 reported with JSON path |
+| sub-agent evicting main KV slot | llama-server with parallel slots | ✅ main pinned to `id_slot 0` |
+
+Sub-agents and parallel sessions get their own branch, so they are never reported as false busts.
+
+## CI gate
+
+```bash
+npx kvguard --record trace.jsonl -- my-agent run-scenario
+npx kvguard check trace.jsonl --fail-on-bust --min-hit-rate 0.95
+```
+
+Prints a Markdown report and exits `1` when a request breaks its parent's prefix.
+
+## Supported
+
+Anthropic `/v1/messages` · OpenAI `/v1/chat/completions` and `/v1/responses` · llama.cpp `llama-server` · Ollama · any OpenAI-compatible server. Prebuilt for Linux (x86_64, arm64), macOS (Intel, Apple Silicon) and Windows (x86_64).
+
+Also available as `uvx kvguard` / `pipx run kvguard` and as a [standalone binary](https://github.com/tranhoangtu-it/kvguard/releases).
+
+**Full documentation, accuracy notes and design:** https://github.com/tranhoangtu-it/kvguard
+
+## License
+
+MIT OR Apache-2.0

package/bin/kvguard.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+// Runs the native kvguard binary, downloading it first when postinstall was skipped
+// (e.g. `npm install --ignore-scripts`).
+"use strict";
+
+const fs = require("node:fs");
+const { spawnSync } = require("node:child_process");
+const { install, BINARY } = require("../install.js");
+
+async function main() {
+  if (!fs.existsSync(BINARY)) {
+    await install();
+  }
+  const result = spawnSync(BINARY, process.argv.slice(2), { stdio: "inherit" });
+  if (result.error) throw result.error;
+  process.exit(result.status ?? 1);
+}
+
+main().catch((err) => {
+  console.error(`kvguard: ${err.message}`);
+  process.exit(1);
+});

package/install.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+// Downloads the kvguard binary for this platform from GitHub Releases, verifies its SHA-256
+// checksum and unpacks it into ./native. Uses only Node built-ins and the system `tar`.
+"use strict";
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const https = require("node:https");
+const os = require("node:os");
+const path = require("node:path");
+const { execFileSync } = require("node:child_process");
+
+const REPO = "tranhoangtu-it/kvguard";
+const TARGETS = {
+  "linux-x64": "x86_64-unknown-linux-musl",
+  "linux-arm64": "aarch64-unknown-linux-musl",
+  "darwin-x64": "x86_64-apple-darwin",
+  "darwin-arm64": "aarch64-apple-darwin",
+  "win32-x64": "x86_64-pc-windows-msvc",
+};
+const MAX_REDIRECTS = 5;
+
+const NATIVE_DIR = path.join(__dirname, "native");
+const BINARY = path.join(NATIVE_DIR, process.platform === "win32" ? "kvguard.exe" : "kvguard");
+
+function assetName(version) {
+  const target = TARGETS[`${process.platform}-${process.arch}`];
+  if (!target) {
+    throw new Error(`kvguard has no prebuilt binary for ${process.platform}-${process.arch}`);
+  }
+  const ext = process.platform === "win32" ? "zip" : "tar.gz";
+  return `kvguard-v${version}-${target}.${ext}`;
+}
+
+function download(url, redirects = 0) {
+  return new Promise((resolve, reject) => {
+    https
+      .get(url, { headers: { "User-Agent": "kvguard-npm-installer" } }, (res) => {
+        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          res.resume();
+          if (redirects >= MAX_REDIRECTS) return reject(new Error(`too many redirects for ${url}`));
+          return resolve(download(new URL(res.headers.location, url).toString(), redirects + 1));
+        }
+        if (res.statusCode !== 200) {
+          res.resume();
+          return reject(new Error(`GET ${url} failed with HTTP ${res.statusCode}`));
+        }
+        const chunks = [];
+        res.on("data", (c) => chunks.push(c));
+        res.on("end", () => resolve(Buffer.concat(chunks)));
+        res.on("error", reject);
+      })
+      .on("error", reject);
+  });
+}
+
+async function install() {
+  const { version } = require("./package.json");
+  const asset = assetName(version);
+  const base = `https://github.com/${REPO}/releases/download/v${version}`;
+  const [archive, checksumFile] = await Promise.all([
+    download(`${base}/${asset}`),
+    download(`${base}/${asset}.sha256`),
+  ]);
+
+  const expected = checksumFile.toString("utf8").trim().split(/\s+/)[0].toLowerCase();
+  const actual = crypto.createHash("sha256").update(archive).digest("hex");
+  if (expected !== actual) {
+    throw new Error(`checksum mismatch for ${asset}: expected ${expected}, got ${actual}`);
+  }
+
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "kvguard-"));
+  try {
+    const archivePath = path.join(tmp, asset);
+    fs.writeFileSync(archivePath, archive);
+    fs.mkdirSync(NATIVE_DIR, { recursive: true });
+    // bsdtar (Windows 10+, macOS) and GNU tar both read .tar.gz; bsdtar also reads .zip.
+    execFileSync("tar", ["-xf", archivePath, "-C", NATIVE_DIR], { stdio: "inherit" });
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+  if (process.platform !== "win32") fs.chmodSync(BINARY, 0o755);
+  return BINARY;
+}
+
+module.exports = { install, BINARY };
+
+if (require.main === module) {
+  install()
+    .then((bin) => console.log(`kvguard installed at ${bin}`))
+    .catch((err) => {
+      console.error(`kvguard: install failed: ${err.message}`);
+      process.exit(1);
+    });
+}

package/package.json

@@ -1,6 +1,23 @@
-{
-  "name": "kvguard",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "kvguard",
+  "version": "0.1.1",
+  "description": "Local proxy & TUI that catches 1-token prompt/KV cache prefix misses and auto-heals requests for Anthropic, OpenAI, llama.cpp and Ollama.",
+  "license": "MIT OR Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tranhoangtu-it/kvguard.git"
+  },
+  "keywords": ["llm", "prompt-caching", "kv-cache", "proxy", "claude", "openai", "llama.cpp", "ollama"],
+  "bin": {
+    "kvguard": "bin/kvguard.js"
+  },
+  "scripts": {
+    "postinstall": "node install.js"
+  },
+  "files": ["bin/", "install.js"],
+  "engines": {
+    "node": ">=18"
+  },
+  "os": ["darwin", "linux", "win32"],
+  "cpu": ["x64", "arm64"]
+}