dsh-context-guardian 0.1.0-alpha.2

package/index.js

@@ -0,0 +1,253 @@
+/**
+ * dsh-context-guardian -- Context Guardian as a native DSH bundle plugin.
+ *
+ * PHASE 1 SCAFFOLD. This file wires the plugin into DSH (config schema,
+ * settings section, the vendored compiler, the optional Python bridge). It
+ * does NOT touch compaction yet: no listener, no provider, no tools. Those
+ * are Phase 3 / 3b and are marked below where they land. Until then
+ * @deepseek-ai/dsh-compaction-basic behaves exactly as the profile has it.
+ *
+ * Written against DSH 0.1.2-alpha.2 (source read 2026-09-19):
+ *   - settings:    packages/settings/settings -> ctx.settings.installSection(owner, ns, schema, entry, hooks)
+ *   - compaction:  packages/compaction/compaction-basic -- `summarize()` is the
+ *                  engine's sole subclass customization hook
+ *   - log seam:    there is no "PreCompact" registration in this DSH; the
+ *                  durable signal is a `session/event` whose type is
+ *                  `compaction/start` (what dsh-openwolf listens to today)
+ *
+ * vendor/compiler.js and vendor/region.js are unmodified from
+ * dsh-compaction-instant@0.1.4 (MIT, TsFreddie; VCC principle by lllyasviel) --
+ * see vendor/LICENSE.dsh-compaction-instant. region.js imports
+ * @deepseek-ai/dsh-compaction and @deepseek-ai/dsh-llm, so it is loaded only
+ * where Phase 3b needs it, never at plugin load.
+ *
+ * MIT licensed.
+ */
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { createInterface } from 'node:readline'
+import { fileURLToPath } from 'node:url'
+import Schema from '@deepseek-ai/schemastery'
+import { COMPILER_REV, DEFAULT_ARG_TOOLS } from './vendor/compiler.js'
+
+export const name = 'dsh-context-guardian'
+
+/** Nothing is required at load in Phase 1; settings attaches when present. */
+export const inject = []
+
+/** Settings namespace (must match /^[a-z][a-z0-9-]*$/). */
+export const SETTINGS_NAMESPACE = 'context-guardian'
+
+/** Resolved from the module URL -- never from process.cwd(). */
+const PACKAGE_ROOT = dirname(fileURLToPath(import.meta.url))
+const BRIDGE_SCRIPT = join(PACKAGE_ROOT, 'modules', 'cg_bridge.py')
+
+const ratio = () => Schema.number().min(0.05).max(0.99)
+
+export const Config = Schema.object({
+  python: Schema.string().default('')
+    .description('Python for the optional bridge. Empty = $GUARDIAN_PYTHON, then a .venv beside this package, then python/python3 on PATH.'),
+  numCtx: Schema.natural().default(32768)
+    .description('Model context window the ratios are measured against (GUARDIAN_NUM_CTX overrides).'),
+  compactThreshold: ratio().default(0.85)
+    .description('Hard compaction trigger (GUARDIAN_COMPACT_THRESHOLD overrides).'),
+  idleCompactRatio: ratio().default(0.45)
+    .description('Proactive trigger when the agent goes idle (GUARDIAN_IDLE_COMPACT_RATIO overrides).'),
+  keepRecentMessages: Schema.natural().default(8)
+    .description('Most recent messages never compacted (GUARDIAN_KEEP_RECENT_MESSAGES overrides).'),
+  reserveOutput: Schema.natural().default(8192)
+    .description('Tokens held back for the reply (GUARDIAN_RESERVE_OUTPUT overrides).'),
+  spanDir: Schema.string().default('')
+    .description('Span archive. Empty = $GUARDIAN_SPAN_DIR, then the proxy\'s own default.'),
+  maxRecallTokens: Schema.natural().default(16000)
+    .description('Cap on one recall restore (GUARDIAN_MAX_RECALL_TOKENS overrides).'),
+  maxSearchHits: Schema.natural().default(50)
+    .description('Cap on one search (GUARDIAN_MAX_SEARCH_HITS overrides).'),
+  toolArgTools: Schema.array(Schema.string()).default([])
+    .description('Tools whose compiled line keeps its key argument. Empty = the compiler\'s DEFAULT_ARG_TOOLS.'),
+  hideTools: Schema.array(Schema.string()).default([])
+    .description('Tools that produce no compiled line at all.'),
+})
+
+/**
+ * Fold the environment over a resolved section. GUARDIAN_* are the names
+ * context_guardian.py and its .env already use.
+ * Precedence: env > settings user layer > patch-row config > schema default.
+ * A malformed or out-of-range env value is ignored, never half-applied.
+ */
+export function resolveOptions(section, env = process.env) {
+  const int = (key, fallback) => {
+    const raw = Number(env[key])
+    return Number.isInteger(raw) && raw > 0 ? raw : fallback
+  }
+  const frac = (key, fallback) => {
+    const raw = Number(env[key])
+    return Number.isFinite(raw) && raw >= 0.05 && raw <= 0.99 ? raw : fallback
+  }
+  return {
+    python: env.GUARDIAN_PYTHON?.trim() || section.python || defaultPython(),
+    numCtx: int('GUARDIAN_NUM_CTX', section.numCtx),
+    compactThreshold: frac('GUARDIAN_COMPACT_THRESHOLD', section.compactThreshold),
+    idleCompactRatio: frac('GUARDIAN_IDLE_COMPACT_RATIO', section.idleCompactRatio),
+    keepRecentMessages: int('GUARDIAN_KEEP_RECENT_MESSAGES', section.keepRecentMessages),
+    reserveOutput: int('GUARDIAN_RESERVE_OUTPUT', section.reserveOutput),
+    spanDir: env.GUARDIAN_SPAN_DIR?.trim() || section.spanDir || '',
+    maxRecallTokens: int('GUARDIAN_MAX_RECALL_TOKENS', section.maxRecallTokens),
+    maxSearchHits: int('GUARDIAN_MAX_SEARCH_HITS', section.maxSearchHits),
+    toolArgTools: section.toolArgTools?.length > 0 ? [...section.toolArgTools] : [...DEFAULT_ARG_TOOLS],
+    hideTools: [...(section.hideTools ?? [])],
+  }
+}
+
+/** Cross-field rule the schema cannot express; refuses the WRITE that breaks it. */
+export function validateSection(section) {
+  if (section.idleCompactRatio >= section.compactThreshold) {
+    throw new Error(`context-guardian: idleCompactRatio (${section.idleCompactRatio}) must be below compactThreshold (${section.compactThreshold})`)
+  }
+}
+
+function defaultPython() {
+  const venv = process.platform === 'win32'
+    ? join(PACKAGE_ROOT, '.venv', 'Scripts', 'python.exe')
+    : join(PACKAGE_ROOT, '.venv', 'bin', 'python')
+  if (existsSync(venv)) return venv
+  return process.platform === 'win32' ? 'python' : 'python3'
+}
+
+/** The optional Python child; see modules/cg_bridge.py for the op list. */
+export class PythonBridge {
+  constructor(options, logger) {
+    this.options = options
+    this.logger = logger
+    this.child = null
+    this.nextId = 1
+    this.pending = new Map()
+    this.stopped = false
+  }
+
+  ensureStarted() {
+    if (this.child !== null) return
+    if (this.stopped) throw new Error('context-guardian bridge is stopped')
+    const env = { ...process.env, PYTHONUNBUFFERED: '1', PYTHONIOENCODING: 'utf-8' }
+    if (this.options.spanDir) env.GUARDIAN_SPAN_DIR ??= this.options.spanDir
+    const child = spawn(this.options.python, [BRIDGE_SCRIPT], {
+      cwd: PACKAGE_ROOT,
+      env,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true, // no console window, no focus steal
+    })
+    this.child = child
+    createInterface({ input: child.stdout }).on('line', line => this.onLine(line))
+    createInterface({ input: child.stderr }).on('line', line => this.logger.debug(`[bridge] ${line}`))
+    child.on('error', error => this.onExit(`spawn failed (${this.options.python}): ${error.message}`))
+    child.on('exit', (code, signal) => this.onExit(`exited code=${code} signal=${signal}`))
+  }
+
+  onLine(line) {
+    let frame
+    try {
+      frame = JSON.parse(line)
+    } catch {
+      this.logger.warn(`context-guardian bridge: non-JSON line on stdout dropped (${line.slice(0, 120)})`)
+      return
+    }
+    const waiter = this.pending.get(frame.id)
+    if (waiter === undefined) return
+    this.pending.delete(frame.id)
+    clearTimeout(waiter.timer)
+    if (frame.ok === true) waiter.resolve(frame.result)
+    else waiter.reject(new Error(String(frame.error ?? 'bridge error')))
+  }
+
+  onExit(reason) {
+    if (this.child === null) return
+    this.child = null
+    for (const waiter of this.pending.values()) {
+      clearTimeout(waiter.timer)
+      waiter.reject(new Error(`context-guardian bridge ${reason}`))
+    }
+    this.pending.clear()
+    if (!this.stopped) this.logger.error(`context-guardian bridge ${reason}`)
+  }
+
+  request(op, params = {}, timeoutMs = 30000) {
+    this.ensureStarted()
+    const id = this.nextId++
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id)
+        reject(new Error(`context-guardian bridge: "${op}" timed out after ${timeoutMs}ms`))
+      }, timeoutMs)
+      this.pending.set(id, { resolve, reject, timer })
+      this.child.stdin.write(`${JSON.stringify({ id, op, ...params })}\n`)
+    })
+  }
+
+  stop() {
+    this.stopped = true
+    const child = this.child
+    if (child === null) return
+    try {
+      child.stdin.write(`${JSON.stringify({ id: 0, op: 'shutdown' })}\n`)
+      child.stdin.end()
+    } catch { /* already gone */ }
+    const killer = setTimeout(() => child.kill(), 3000)
+    killer.unref()
+    child.once('exit', () => clearTimeout(killer))
+  }
+}
+
+export function apply(ctx, config) {
+  validateSection(config) // a bad patch row fails the load, loudly
+
+  let source = () => config
+  let bridge = null
+
+  const stopBridge = () => {
+    if (bridge === null) return
+    bridge.stop()
+    bridge = null
+  }
+
+  /** Current options; every Phase 3 consumer reads through this, never a copy. */
+  const options = () => resolveOptions(source())
+
+  /** Spawned on first use only -- Phase 1 never calls it on its own. */
+  // eslint-disable-next-line no-unused-vars
+  const getBridge = () => {
+    bridge ??= new PythonBridge(options(), ctx.logger)
+    return bridge
+  }
+
+  ctx.inject(['settings'], (settingsCtx) => {
+    settingsCtx.settings.installSection(ctx, SETTINGS_NAMESPACE, Config, config, {
+      validate: validateSection,
+      setSource: (current) => {
+        source = current
+      },
+      // Thresholds are read through options() at decision time, so a change
+      // needs no work here; only the interpreter / span dir are spawn-time.
+      onChange: () => {
+        if (bridge === null) return
+        const next = options()
+        if (next.python !== bridge.options.python || next.spanDir !== bridge.options.spanDir) stopBridge()
+      },
+    })
+  })
+
+  ctx.effect(() => stopBridge)
+
+  const now = options()
+  ctx.logger.info(`context-guardian scaffold loaded (compiler ${COMPILER_REV}; window ${now.numCtx}, hard ${now.compactThreshold}, idle ${now.idleCompactRatio}) -- compaction untouched in Phase 1`)
+
+  // ── PHASE 3 lands here ────────────────────────────────────────────────────
+  // 3.1  snapshot on ctx.on('session/event', ...) where event type is
+  //      'compaction/start' (absorbing dsh-openwolf's compactionSurvival, 3d)
+  // 3.2  compaction: subclass @deepseek-ai/dsh-compaction-basic and override
+  //      summarize() with vendor/compiler.js compileRegion() -- 3b / 3c
+  // 3b   recall + search tools via ctx.tools.register(defineTool(...)), the
+  //      /recall command, toolArgTools / hideTools, recall + search budgets
+  // 3c   context_rewrite_cost, idle trigger, tier ladder, keyword index,
+  //      context_compact
+}

package/modules/cg_bridge.py

@@ -0,0 +1,251 @@
+#!/usr/bin/env python3
+"""
+cg_bridge.py -- private bridge between the dsh-context-guardian DSH plugin
+(Node) and the Python Context Guardian in this repo.
+
+Inside DSH, compaction itself is done in-process by the plugin (the vendored
+deterministic compiler) -- no Python on the hot path. This bridge exists so the
+plugin and the HTTP proxy stay ONE product: it reports the proxy's resolved
+GUARDIAN_* configuration and reads the span archive the proxy has already
+written, so recall/search can reach history compacted before the plugin
+existed. The proxy (`context-guardian` / `context_guardian.py`) is untouched
+and keeps working for anyone who prefers that path.
+
+PROTOCOL -- one JSON object per line, both directions, UTF-8 (same framing as
+dsh-tool-guardian's tg_bridge.py):
+    request   {"id": <int>, "op": "<name>", ...params}
+    response  {"id": <int>, "ok": true,  "result": {...}}
+              {"id": <int>, "ok": false, "error": "<Type>: <message>"}
+
+    hello      -> versions + interpreter. Imports NOTHING heavy; liveness probe.
+    config     -> the proxy's resolved settings (imports context_guardian,
+                  which needs its requirements.txt installed; fails loud if not)
+    spans      {"limit": <int>?} -> newest span files in the archive
+    shutdown   -> exits 0
+
+    python cg_bridge.py              serve on stdio
+    python cg_bridge.py --selftest   offline checks, stdlib only
+
+Python >= 3.10 -- same floor as context_guardian.py. MIT licensed.
+"""
+from __future__ import annotations
+
+import io
+import json
+import os
+import platform
+import sys
+import tempfile
+from pathlib import Path
+
+BRIDGE_VERSION = "0.1.0"
+
+# context_guardian.py lives one level above modules/, in the repo AND in the
+# published npm package. Resolved from __file__, never from the working dir.
+PACKAGE_ROOT = Path(__file__).resolve().parent.parent
+
+CONFIG_FIELDS = ("GUARDIAN_PORT", "GUARDIAN_HOST", "UPSTREAM_URL", "NUM_CTX",
+                 "COMPACT_THRESHOLD", "RESERVE_OUTPUT", "KEEP_RECENT_MESSAGES",
+                 "CHARS_PER_TOKEN_ESTIMATE", "KEEP_SPANS", "KEEP_SUMMARIES")
+
+
+def default_span_dir() -> Path:
+    """The proxy's own rule, restated without importing it: env, else
+    <package>/logs/guardian_spans."""
+    return Path(os.environ.get("GUARDIAN_SPAN_DIR",
+                               str(PACKAGE_ROOT / "logs" / "guardian_spans")))
+
+
+def _load_proxy():
+    if str(PACKAGE_ROOT) not in sys.path:
+        sys.path.insert(0, str(PACKAGE_ROOT))
+    import context_guardian  # noqa: PLC0415  (heavy: fastapi/httpx; on demand only)
+    return context_guardian
+
+
+class Bridge:
+    def __init__(self, load_proxy=_load_proxy, span_dir=None):
+        self._load_proxy = load_proxy      # injectable: selftest passes a fake
+        self._span_dir = span_dir
+
+    def op_hello(self, _req: dict) -> dict:
+        return {"bridge": BRIDGE_VERSION,
+                "python": platform.python_version(),
+                "executable": sys.executable,
+                "package_root": str(PACKAGE_ROOT),
+                "pid": os.getpid()}
+
+    def op_config(self, _req: dict) -> dict:
+        cg = self._load_proxy()
+        out = {name: getattr(cg, name) for name in CONFIG_FIELDS if hasattr(cg, name)}
+        out["SPAN_DIR"] = str(getattr(cg, "SPAN_DIR", default_span_dir()))
+        out["version"] = getattr(cg, "__version__", "unknown")
+        return out
+
+    def op_spans(self, req: dict) -> dict:
+        root = Path(self._span_dir) if self._span_dir else default_span_dir()
+        limit = max(1, min(int(req.get("limit") or 50), 500))
+        if not root.is_dir():
+            # Absent is reported as absent, never as an empty archive.
+            return {"dir": str(root), "exists": False, "spans": []}
+        files = sorted((p for p in root.iterdir() if p.is_file()),
+                       key=lambda p: p.stat().st_mtime, reverse=True)
+        return {"dir": str(root), "exists": True, "total": len(files),
+                "spans": [{"name": p.name, "bytes": p.stat().st_size,
+                           "mtime": p.stat().st_mtime} for p in files[:limit]]}
+
+    def op_shutdown(self, _req: dict) -> dict:
+        return {"exit": True}
+
+    def dispatch(self, req: dict) -> dict:
+        rid = req.get("id")
+        op = str(req.get("op") or "")
+        fn = getattr(self, "op_" + op, None)
+        if fn is None:
+            return {"id": rid, "ok": False, "error": "UnknownOp: %r" % op}
+        try:
+            return {"id": rid, "ok": True, "result": fn(req)}
+        except Exception as exc:  # noqa: BLE001
+            return {"id": rid, "ok": False,
+                    "error": "%s: %s" % (type(exc).__name__, exc)}
+
+
+def serve(stdin, proto, bridge=None) -> int:
+    bridge = bridge or Bridge()
+    for line in stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            req = json.loads(line)
+            if not isinstance(req, dict):
+                raise ValueError("frame is not an object")
+        except ValueError as exc:
+            reply = {"id": None, "ok": False, "error": "BadFrame: %s" % exc}
+        else:
+            reply = bridge.dispatch(req)
+        proto.write(json.dumps(reply, ensure_ascii=False) + "\n")
+        proto.flush()
+        if reply.get("ok") and (reply.get("result") or {}).get("exit"):
+            return 0
+    return 0
+
+
+# ------------------------------------------------------------- selftest -----
+
+class _FakeProxy:
+    __version__ = "9.9.9"
+    NUM_CTX = 32768
+    COMPACT_THRESHOLD = 0.85
+    SPAN_DIR = Path("fake-spans")
+
+
+def _check_hello_needs_no_proxy_import() -> bool:
+    def boom():
+        raise AssertionError("hello must not import the proxy")
+    r = Bridge(load_proxy=boom).dispatch({"id": 1, "op": "hello"})
+    return r.get("ok") is True and r["result"]["bridge"] == BRIDGE_VERSION
+
+
+def _check_config_reports_proxy_constants() -> bool:
+    r = Bridge(load_proxy=lambda: _FakeProxy).dispatch({"id": 2, "op": "config"})
+    res = r.get("result") or {}
+    return (r.get("ok") is True and res.get("NUM_CTX") == 32768
+            and res.get("COMPACT_THRESHOLD") == 0.85
+            and res.get("version") == "9.9.9" and res.get("SPAN_DIR") == "fake-spans")
+
+
+def _check_config_import_failure_is_loud() -> bool:
+    def missing():
+        raise ImportError("No module named 'fastapi'")
+    r = Bridge(load_proxy=missing).dispatch({"id": 3, "op": "config"})
+    return r.get("ok") is False and "fastapi" in str(r.get("error"))
+
+
+def _check_missing_span_dir_is_absent_not_empty() -> bool:
+    with tempfile.TemporaryDirectory() as tmp:
+        r = Bridge(span_dir=str(Path(tmp) / "nope")).dispatch({"id": 4, "op": "spans"})
+    res = r.get("result") or {}
+    return r.get("ok") is True and res.get("exists") is False and res.get("spans") == []
+
+
+def _check_spans_lists_newest_first_with_limit() -> bool:
+    with tempfile.TemporaryDirectory() as tmp:
+        for i, name in enumerate(("a.json", "b.json", "c.json")):
+            p = Path(tmp) / name
+            p.write_text("{}", encoding="utf-8")
+            os.utime(p, (1000 + i, 1000 + i))
+        r = Bridge(span_dir=tmp).dispatch({"id": 5, "op": "spans", "limit": 2})
+    res = r.get("result") or {}
+    return (res.get("total") == 3
+            and [s["name"] for s in res.get("spans", [])] == ["c.json", "b.json"])
+
+
+def _check_default_span_dir_is_under_package_root() -> bool:
+    saved = os.environ.pop("GUARDIAN_SPAN_DIR", None)
+    try:
+        d = default_span_dir()
+    finally:
+        if saved is not None:
+            os.environ["GUARDIAN_SPAN_DIR"] = saved
+    return (d == PACKAGE_ROOT / "logs" / "guardian_spans"
+            and (PACKAGE_ROOT / "context_guardian.py").is_file()
+            and PACKAGE_ROOT.name != "modules")
+
+
+def _check_serve_roundtrip_and_shutdown_exits() -> bool:
+    stdin = io.StringIO('{"id": 7, "op": "hello"}\nnot json\n{"id": 8, "op": "shutdown"}\n'
+                        '{"id": 9, "op": "hello"}\n')
+    proto = io.StringIO()
+    code = serve(stdin, proto)
+    frames = [json.loads(x) for x in proto.getvalue().splitlines()]
+    return (code == 0 and len(frames) == 3
+            and frames[0]["id"] == 7 and frames[0]["ok"] is True
+            and "BadFrame" in frames[1]["error"]
+            and frames[2]["result"]["exit"] is True)
+
+
+CHECKS = [
+    ("hello_needs_no_proxy_import", _check_hello_needs_no_proxy_import),
+    ("config_reports_proxy_constants", _check_config_reports_proxy_constants),
+    ("config_import_failure_is_loud", _check_config_import_failure_is_loud),
+    ("missing_span_dir_is_absent_not_empty", _check_missing_span_dir_is_absent_not_empty),
+    ("spans_lists_newest_first_with_limit", _check_spans_lists_newest_first_with_limit),
+    ("default_span_dir_is_under_package_root", _check_default_span_dir_is_under_package_root),
+    ("serve_roundtrip_and_shutdown_exits", _check_serve_roundtrip_and_shutdown_exits),
+]
+
+
+def selftest() -> int:
+    passed = 0
+    for name, fn in CHECKS:
+        try:
+            ok = fn() is True
+        except Exception as exc:  # noqa: BLE001
+            ok = False
+            print("  FAIL %s (%s: %s)" % (name, type(exc).__name__, exc))
+        else:
+            print("  %s %s" % ("ok  " if ok else "FAIL", name))
+        if ok:
+            passed += 1
+    total = len(CHECKS)
+    print("cg_bridge selftest: %d checks, %d passed, %d failed"
+          % (total, passed, total - passed))
+    return 0 if total > 0 and passed == total else 1
+
+
+def main(argv=None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if "--selftest" in argv:
+        return selftest()
+    if "--version" in argv:
+        print(BRIDGE_VERSION)
+        return 0
+    proto = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8", newline="\n")
+    stdin = io.TextIOWrapper(sys.stdin.buffer, encoding="utf-8", errors="replace")
+    sys.stdout = sys.stderr  # nothing but `proto` may reach the real stdout
+    return serve(stdin, proto)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "dsh-context-guardian",
+  "version": "0.1.0-alpha.2",
+  "description": "Context Guardian as a native DeepSeek Harness (DSH) bundle: deterministic, seq-pointer-preserving compaction with model-facing recall and search. Companion to dsh-tool-guardian.",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./engine": "./engine.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "engine.js",
+    "cg_recall.js",
+    "cordis.patch.yml",
+    "modules/cg_bridge.py",
+    "vendor/compiler.js",
+    "vendor/region.js",
+    "vendor/LICENSE.dsh-compaction-instant",
+    "context_guardian.py",
+    "configure.py",
+    "requirements.txt",
+    "docs/dsh-integration.md",
+    "THIRD_PARTY_NOTICES.md",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {
+    "check": "node --check index.js && node --check engine.js && node --check cg_recall.js && node --check vendor/compiler.js",
+    "selftest": "python modules/cg_bridge.py --selftest",
+    "test:node": "node tests/probes/probe_cg_recall.mjs && node cg_recall.js --selftest && node tests/engine_smoke.mjs"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.2"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-compaction": ">=0.1.2-alpha.2",
+    "@deepseek-ai/dsh-llm": ">=0.1.2-alpha.2",
+    "@deepseek-ai/dsh-tools": ">=0.1.2-alpha.2"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "dsh-bundle",
+    "deepseek-harness",
+    "compaction",
+    "context-window",
+    "context-management",
+    "recall",
+    "local-llm",
+    "ollama"
+  ],
+  "license": "MIT",
+  "author": "LuminariSoftwares",
+  "homepage": "https://github.com/LuminariSoftwares/context-guardian",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LuminariSoftwares/context-guardian.git"
+  },
+  "bugs": {
+    "url": "https://github.com/LuminariSoftwares/context-guardian/issues"
+  }
+}

package/requirements.txt

@@ -0,0 +1,4 @@
+fastapi>=0.110
+uvicorn[standard]>=0.29
+httpx>=0.27
+python-dotenv>=1.0

package/vendor/LICENSE.dsh-compaction-instant

@@ -0,0 +1,28 @@
+compiler.js and region.js in this directory are vendored, unmodified, from
+dsh-compaction-instant@0.1.4 (npm; author TsFreddie), md5:
+  e74bb51763795abd1a839e61de4875fa  compiler.js
+  dc719f0745a532dd80ef1a3125f3bf6d  region.js
+The compiler ports the principle of https://github.com/lllyasviel/VCC
+(skills/conversation-compiler/scripts/VCC.py). Their original headers are kept.
+
+MIT License
+
+Copyright (c) 2026 TsFreddie
+
+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.