@parad0x_labs/openclaw-context-capsule 1.4.0 → 1.7.0

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * context-capsule ContextEngine plugin for OpenClaw.
+ *
+ * Compresses older session history before it reaches the LLM, while keeping a
+ * recent verbatim tail for coherence. Older turns become a bounded extractive
+ * capsule containing durable facts, decisions, tasks, errors, paths, and links.
+ *
+ * Self-contained:
+ *   The compression core is vendored inline (./compression.ts). There is no
+ *   external runtime dependency. The plugin makes no network requests, no file
+ *   system access, and no on-chain calls. Everything runs locally.
+ *
+ * Data handling:
+ *   Text content is passed through an inline vault-scan gate before reaching the
+ *   compression core OR the model, including short sessions, verbatim tails, and
+ *   compression error fallbacks. No matched values are logged; only category
+ *   counts are emitted. Redaction is best-effort pattern matching, not a formal
+ *   privacy guarantee.
+ */
+declare const _default: any;
+export default _default;

package/dist/index.js

@@ -0,0 +1,290 @@
+/**
+ * context-capsule ContextEngine plugin for OpenClaw.
+ *
+ * Compresses older session history before it reaches the LLM, while keeping a
+ * recent verbatim tail for coherence. Older turns become a bounded extractive
+ * capsule containing durable facts, decisions, tasks, errors, paths, and links.
+ *
+ * Self-contained:
+ *   The compression core is vendored inline (./compression.ts). There is no
+ *   external runtime dependency. The plugin makes no network requests, no file
+ *   system access, and no on-chain calls. Everything runs locally.
+ *
+ * Data handling:
+ *   Text content is passed through an inline vault-scan gate before reaching the
+ *   compression core OR the model, including short sessions, verbatim tails, and
+ *   compression error fallbacks. No matched values are logged; only category
+ *   counts are emitted. Redaction is best-effort pattern matching, not a formal
+ *   privacy guarantee.
+ */
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { delegateCompactionToRuntime } from "openclaw/plugin-sdk/core";
+import { compressContext, injectCapsule } from "./compression.js";
+const VAULT_PATTERNS = [
+    {
+        key: "pem_key",
+        re: /-----BEGIN (?:[A-Z ]+ )?PRIVATE KEY-----[\s\S]*?-----END (?:[A-Z ]+ )?PRIVATE KEY-----/gi,
+        placeholder: "[REDACTED_PRIVATE_KEY]",
+    },
+    { key: "anthropic", re: /sk-ant-[A-Za-z0-9\-_]{20,}/g, placeholder: "[REDACTED_ANTHROPIC_KEY]" },
+    { key: "openai_project", re: /sk-proj-[A-Za-z0-9_\-]{40,}/g, placeholder: "[REDACTED_OPENAI_PROJECT_KEY]" },
+    { key: "openai", re: /sk-[A-Za-z0-9]{20,}T3BlbkFJ[A-Za-z0-9]{20,}/g, placeholder: "[REDACTED_OPENAI_KEY]" },
+    { key: "generic_sk", re: /\bsk-[A-Za-z0-9]{20,}\b/g, placeholder: "[REDACTED_SK_KEY]" },
+    { key: "github", re: /gh[pousr]_[A-Za-z0-9_]{36,}/g, placeholder: "[REDACTED_GITHUB_TOKEN]" },
+    { key: "slack", re: /xox[bpras]-[A-Za-z0-9\-]{10,}/g, placeholder: "[REDACTED_SLACK_TOKEN]" },
+    { key: "aws", re: /AKIA[0-9A-Z]{16}/g, placeholder: "[REDACTED_AWS_KEY]" },
+    { key: "stripe", re: /(?:sk|pk)_(?:test|live)_[A-Za-z0-9]{24,}/g, placeholder: "[REDACTED_STRIPE_KEY]" },
+    { key: "jwt", re: /eyJ[A-Za-z0-9_\-]{8,}\.[A-Za-z0-9_\-]{8,}\.[A-Za-z0-9_\-]{8,}/g, placeholder: "[REDACTED_JWT]" },
+    { key: "bearer", re: /Bearer\s+[A-Za-z0-9\-._~+/]+=*/gi, placeholder: "[REDACTED_BEARER]" },
+    {
+        key: "credential",
+        re: /(?:password|passwd|secret|token|api[_-]?key|access[_-]?key|auth[_-]?token)\s*[=:]\s*["']?([A-Za-z0-9/+=\-_.]{8,})["']?/gi,
+        placeholder: "[REDACTED_SECRET]",
+    },
+    { key: "card", re: /\b(?:4\d{3}|5[1-5]\d{2}|3[47]\d{2})[ -]?\d{4}[ -]?\d{4}[ -]?\d{4}\b/g, placeholder: "[REDACTED_CC]" },
+];
+const DEFAULT_MIN_MESSAGES = 20;
+const DEFAULT_KEEP_RECENT = 10;
+// Tuned for fidelity over raw token-cut: ~1400 tokens lands near the knee of the
+// recall/compression curve (~5x reduction at ~70%+ key-signal recall on real
+// sessions) instead of the old 700 (~7.5x but ~43% recall). A high compression
+// ratio is worthless if the decisions, errors, and refs don't survive.
+const DEFAULT_MAX_CAPSULE_TOKENS = 1400;
+const DEFAULT_CAPSULE_TOKEN_RATIO = 0.14;
+const DEFAULT_MIN_COMPRESS_TOKENS = 900;
+const MIN_TAIL_MESSAGES = 2;
+function vaultGuard(text, label) {
+    let result = text;
+    const hits = {};
+    for (const { key, re, placeholder } of VAULT_PATTERNS) {
+        re.lastIndex = 0;
+        const matches = result.match(re);
+        if (matches?.length) {
+            hits[key] = (hits[key] ?? 0) + matches.length;
+            re.lastIndex = 0;
+            result = result.replace(re, placeholder);
+        }
+    }
+    const total = Object.values(hits).reduce((a, b) => a + b, 0);
+    if (total > 0) {
+        const summary = Object.entries(hits)
+            .map(([k, n]) => `${k}x${n}`)
+            .join(", ");
+        console.warn(`[context-capsule vault] ${label}: redacted ${total} (${summary})`);
+    }
+    return result;
+}
+function numberFromConfig(value, fallback, min, max) {
+    const n = typeof value === "number" ? value : Number(value);
+    if (!Number.isFinite(n))
+        return fallback;
+    return Math.max(min, Math.min(max, n));
+}
+function integerFromConfig(value, fallback, min, max) {
+    return Math.floor(numberFromConfig(value, fallback, min, max));
+}
+function getOwnRecord(value, key) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    return value[key];
+}
+function readPluginConfig(ctx) {
+    const config = getOwnRecord(getOwnRecord(getOwnRecord(ctx, "config"), "plugins"), "entries");
+    const raw = getOwnRecord(config, "context-capsule");
+    const record = raw && typeof raw === "object" ? raw : {};
+    return {
+        minMessages: integerFromConfig(record.minMessages, DEFAULT_MIN_MESSAGES, 1, 10000),
+        keepRecentMessages: integerFromConfig(record.keepRecentMessages, DEFAULT_KEEP_RECENT, 1, 200),
+        maxCapsuleTokens: integerFromConfig(record.maxCapsuleTokens, DEFAULT_MAX_CAPSULE_TOKENS, 120, 4000),
+        capsuleTokenRatio: numberFromConfig(record.capsuleTokenRatio, DEFAULT_CAPSULE_TOKEN_RATIO, 0.01, 0.5),
+        minCompressTokens: integerFromConfig(record.minCompressTokens, DEFAULT_MIN_COMPRESS_TOKENS, 0, 1000000),
+    };
+}
+function normalizeRole(role) {
+    return role === "toolResult" ? "tool" : typeof role === "string" ? role : "unknown";
+}
+function contentToText(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .map((block) => {
+        if (!block || typeof block !== "object")
+            return "";
+        const b = block;
+        if (b.type === "text" && typeof b.text === "string")
+            return b.text;
+        if (b.type === "toolResult" || b.type === "tool_result")
+            return contentToText(b.content);
+        return "";
+    })
+        .filter(Boolean)
+        .join("\n");
+}
+function normalizeMessages(messages) {
+    return messages.map((msg) => ({
+        role: normalizeRole(msg.role),
+        content: contentToText(msg.content),
+    }));
+}
+function redactContent(content, label) {
+    if (typeof content === "string") {
+        const clean = vaultGuard(content, label);
+        return { content: clean, changed: clean !== content };
+    }
+    if (!Array.isArray(content))
+        return { content, changed: false };
+    let changed = false;
+    const next = content.map((block, index) => {
+        if (!block || typeof block !== "object")
+            return block;
+        const b = block;
+        if (typeof b.text === "string") {
+            const clean = vaultGuard(b.text, `${label}.text[${index}]`);
+            if (clean !== b.text) {
+                changed = true;
+                return { ...b, text: clean };
+            }
+        }
+        if ("content" in b) {
+            const nested = redactContent(b.content, `${label}.content[${index}]`);
+            if (nested.changed) {
+                changed = true;
+                return { ...b, content: nested.content };
+            }
+        }
+        return block;
+    });
+    return { content: next, changed };
+}
+function redactMessage(msg, index) {
+    if (!("content" in msg))
+        return msg;
+    const role = normalizeRole(msg.role);
+    const redacted = redactContent(msg.content, `msg[${index}:${role}]`);
+    return redacted.changed ? { ...msg, content: redacted.content } : msg;
+}
+/** Rough token estimate: ~4 chars per token, including text blocks. */
+function estimateTokens(messages) {
+    return normalizeMessages(messages).reduce((sum, m) => sum + Math.ceil(m.content.length / 4), 0);
+}
+function resolveCapsuleTokenBudget(cfg, tokenBudget) {
+    if (!Number.isFinite(tokenBudget) || !tokenBudget || tokenBudget <= 0) {
+        return cfg.maxCapsuleTokens;
+    }
+    return Math.max(120, Math.min(cfg.maxCapsuleTokens, Math.floor(tokenBudget * cfg.capsuleTokenRatio)));
+}
+function resolveKeepRecentCount(params) {
+    const { messages, cfg, tokenBudget } = params;
+    let keep = Math.min(cfg.keepRecentMessages, messages.length);
+    if (!Number.isFinite(tokenBudget) || !tokenBudget || tokenBudget <= 0)
+        return keep;
+    const tailBudget = Math.max(600, Math.floor(tokenBudget * 0.35));
+    while (keep > MIN_TAIL_MESSAGES && estimateTokens(messages.slice(-keep)) > tailBudget) {
+        keep -= 1;
+    }
+    return keep;
+}
+class ContextCapsuleEngine {
+    info = {
+        id: "context-capsule",
+        name: "Context Capsule",
+        version: "1.7.0",
+        ownsCompaction: false,
+        turnMaintenanceMode: "background",
+    };
+    cfg;
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    async ingest(_params) {
+        return { ingested: true };
+    }
+    async assemble(params) {
+        const scannedMessages = params.messages.map((msg, index) => redactMessage(msg, index));
+        const totalTokens = estimateTokens(scannedMessages);
+        if (scannedMessages.length < this.cfg.minMessages ||
+            totalTokens < this.cfg.minCompressTokens ||
+            scannedMessages.length <= MIN_TAIL_MESSAGES) {
+            return {
+                messages: scannedMessages,
+                estimatedTokens: totalTokens,
+            };
+        }
+        const keepRecent = resolveKeepRecentCount({
+            messages: scannedMessages,
+            cfg: this.cfg,
+            tokenBudget: params.tokenBudget,
+        });
+        const tail = scannedMessages.slice(-keepRecent);
+        const older = scannedMessages.slice(0, -keepRecent);
+        if (older.length === 0) {
+            return {
+                messages: scannedMessages,
+                estimatedTokens: totalTokens,
+            };
+        }
+        const capsuleTokens = resolveCapsuleTokenBudget(this.cfg, params.tokenBudget);
+        const normalized = normalizeMessages(older).filter((msg) => msg.content.trim().length > 0);
+        if (normalized.length === 0) {
+            return {
+                messages: tail,
+                estimatedTokens: estimateTokens(tail),
+            };
+        }
+        let summaryText;
+        try {
+            const capsule = compressContext(normalized, {
+                sessionId: params.sessionId,
+                maxOutputTokens: capsuleTokens,
+            });
+            summaryText = injectCapsule(capsule, { maxOutputTokens: capsuleTokens });
+        }
+        catch (err) {
+            console.warn("[context-capsule] Compression failed; falling back to vault-scanned messages.", err instanceof Error ? err.message : String(err));
+            return {
+                messages: scannedMessages,
+                estimatedTokens: totalTokens,
+                promptAuthority: "preassembly_may_overflow",
+            };
+        }
+        // Deliver the capsule via systemPromptAddition — the ONLY supported channel
+        // that reaches the model. OpenClaw's provider adapters (Anthropic, OpenAI)
+        // emit only user/assistant/toolResult messages and SILENTLY DROP any other
+        // role, so a role:"system" message placed in `messages` would never reach the
+        // model. `messages` therefore carries only the verbatim recent tail (valid
+        // roles); the compressed older history rides in systemPromptAddition, which
+        // OpenClaw merges into the system prompt.
+        const systemPromptAddition = `[Context Capsule — compressed older conversation history]\n${summaryText}\n\n` +
+            "The block above is a lossy extractive capsule of earlier turns (the recent " +
+            "messages below it remain verbatim). Use it for continuity; ask the user to " +
+            "restate exact wording when precision matters. Anything marked superseded/~~ " +
+            "was abandoned — do not act on it.";
+        return {
+            messages: tail,
+            estimatedTokens: estimateTokens(tail) + Math.ceil(systemPromptAddition.length / 4),
+            systemPromptAddition,
+        };
+    }
+    async compact(params) {
+        // Transcript compaction (shrinking the stored session when it nears the model
+        // context) is delegated to OpenClaw's native runtime bridge — the SAME path
+        // the built-in legacy engine uses. A stub that merely returns
+        // {compacted:false} is treated as a compaction FAILURE by the CLI/gateway
+        // (it throws "transcript compaction failed"), which breaks long sessions.
+        return await delegateCompactionToRuntime(params);
+    }
+}
+export default definePluginEntry({
+    id: "context-capsule",
+    name: "Context Capsule",
+    description: "Context engine that compresses older agent session history into a bounded, " +
+        "extractive capsule before the model call, keeping recent messages verbatim. " +
+        "It preserves durable facts, tasks, decisions, errors, files, commands, and " +
+        "links while cutting prompt tokens on long-running sessions. Compression and " +
+        "best-effort secret redaction run locally with no network or file-system access.",
+    register(api) {
+        api.registerContextEngine("context-capsule", (ctx) => new ContextCapsuleEngine(readPluginConfig(ctx)));
+    },
+});

package/dist/platform.d.ts

@@ -0,0 +1,14 @@
+/** SHA-256 of a UTF-8 string (or raw bytes) -> 32 bytes. */
+export declare function sha256Bytes(data: string | Uint8Array): Uint8Array;
+/** SHA-256 of a UTF-8 string -> lowercase hex. */
+export declare function sha256Hex(data: string): string;
+/** SHA-256 of (a ‖ b) raw bytes — the merkle internal-node hash. */
+export declare function sha256Concat(a: Uint8Array, b: Uint8Array): Uint8Array;
+/** Deflate (zlib, level 9) a UTF-8 string -> base64 + raw byte length. */
+export declare function deflate(text: string): {
+    base64: string;
+    bytes: number;
+};
+export declare function utf8ByteLength(text: string): number;
+export declare function zeroBytes(n: number): Uint8Array;
+export declare function bytesToHex(bytes: Uint8Array): string;

package/dist/platform.js

@@ -0,0 +1,46 @@
+/**
+ * Platform crypto/compression primitives for the context-capsule core.
+ *
+ * This is the DEFAULT (Node) implementation — `node:crypto` + `node:zlib`, the
+ * exact behavior the published OpenClaw plugin has always had (zero runtime
+ * deps). The compression core imports these names instead of the Node builtins
+ * directly so the SAME source can run in a browser: a browser build aliases this
+ * module to `platform.browser.ts` (pure-JS @noble/hashes + pako). The two
+ * backends agree on everything that matters — see test/platform-parity.test.mjs:
+ *   • SHA-256 is byte-identical, so a capsule's merkleRoot, capsuleId, and the
+ *     injected memory the model sees are byte-identical across backends.
+ *   • deflate is interoperable/round-trip-identical (each inflates the other's
+ *     output to the exact original); compressed BYTES may differ on highly
+ *     repetitive input — which never affects integrity, since the merkle root is
+ *     built over sha256 leaves, not the compressed blob.
+ * No source line of compression.ts cares which backend is active.
+ */
+import { createHash } from "node:crypto";
+import { deflateSync } from "node:zlib";
+/** SHA-256 of a UTF-8 string (or raw bytes) -> 32 bytes. */
+export function sha256Bytes(data) {
+    const buf = typeof data === "string" ? Buffer.from(data, "utf8") : Buffer.from(data);
+    return new Uint8Array(createHash("sha256").update(buf).digest());
+}
+/** SHA-256 of a UTF-8 string -> lowercase hex. */
+export function sha256Hex(data) {
+    return createHash("sha256").update(Buffer.from(data, "utf8")).digest("hex");
+}
+/** SHA-256 of (a ‖ b) raw bytes — the merkle internal-node hash. */
+export function sha256Concat(a, b) {
+    return new Uint8Array(createHash("sha256").update(Buffer.from(a)).update(Buffer.from(b)).digest());
+}
+/** Deflate (zlib, level 9) a UTF-8 string -> base64 + raw byte length. */
+export function deflate(text) {
+    const out = deflateSync(Buffer.from(text, "utf8"), { level: 9 });
+    return { base64: out.toString("base64"), bytes: out.length };
+}
+export function utf8ByteLength(text) {
+    return Buffer.byteLength(text, "utf8");
+}
+export function zeroBytes(n) {
+    return new Uint8Array(n);
+}
+export function bytesToHex(bytes) {
+    return Buffer.from(bytes).toString("hex");
+}

package/openclaw.plugin.json

@@ -17,6 +17,23 @@
         "type": "integer",
         "minimum": 1,
         "description": "Number of most-recent messages kept verbatim after compression. Default: 10."
+      },
+      "maxCapsuleTokens": {
+        "type": "integer",
+        "minimum": 120,
+        "maximum": 4000,
+        "description": "Maximum tokens reserved for the injected extractive capsule. Default: 1400 (tuned for fidelity — near the knee of the recall/compression curve)."
+      },
+      "capsuleTokenRatio": {
+        "type": "number",
+        "minimum": 0.01,
+        "maximum": 0.5,
+        "description": "When the host provides a model token budget, cap the capsule at this fraction of that budget. Default: 0.14."
+      },
+      "minCompressTokens": {
+        "type": "integer",
+        "minimum": 0,
+        "description": "Minimum estimated transcript tokens before compression is applied. Default: 900."
       }
     }
   }

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@parad0x_labs/openclaw-context-capsule",
-  "version": "1.4.0",
-  "description": "Self-contained OpenClaw context engine that compresses long agent session history (> 20 messages) into a compact capsule before the model call, keeping the last 10 messages verbatim. Cuts token cost on long chats with any model. No external runtime dependencies; no network, file, or on-chain access.",
+  "version": "1.7.0",
+  "description": "Self-contained OpenClaw context engine that compresses older agent session history into a bounded extractive capsule, preserving decisions, tasks, errors, files, links, and durable facts while keeping recent messages verbatim.",
   "type": "module",
-  "main": "./src/index.ts",
+  "main": "./dist/index.js",
   "files": [
-    "src/",
+    "dist/",
     "openclaw.plugin.json",
-    "README.md"
+    "README.md",
+    "SKILL.md",
+    "CHANGELOG.md"
   ],
   "keywords": [
     "openclaw",
@@ -20,21 +22,32 @@
   ],
   "openclaw": {
     "extensions": [
-      "./src/index.ts"
+      "./dist/index.js"
     ],
-    "compat": {
-      "pluginApi": "1.x"
-    },
     "build": {
-      "openclawVersion": ">=1.0.0"
+      "openclawVersion": ">=2026.6.0"
     }
   },
+  "devDependencies": {
+    "@noble/hashes": "^2.2.0",
+    "@types/node": "^22.0.0",
+    "pako": "^2.1.0",
+    "typescript": "^5.6.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run build && npm test",
+    "test": "npm run build && node test/compression-smoke.mjs && node test/quality.test.mjs && node test/value-survival.test.mjs && node test/supersession-bench.mjs && node test/hardening-bench.mjs && node test/secret-bench.mjs && node test/platform-parity.test.mjs"
+  },
   "engines": {
     "node": ">=22"
   },
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Parad0x-Labs/dna-x402"
+    "url": "https://github.com/Parad0x-Labs/openclaw-skills",
+    "directory": "skills/context-capsule"
   }
 }

package/src/compression.ts

@@ -1,176 +0,0 @@
-/**
- * Self-contained compression core for the Context Capsule skill.
- *
- * This is a VENDORED, MINIMAL SUBSET of @parad0x_labs/context-capsule —
- * only the two pure functions this plugin actually uses (compressContext +
- * injectCapsule) and their local helpers. It is bundled directly in the skill
- * so the published artifact is fully self-contained and auditable: there is no
- * external runtime dependency, and nothing here performs network I/O, file
- * access, dynamic imports, or on-chain anchoring.
- *
- * Dependencies: Node.js built-ins only — `node:zlib` (deflate) and
- * `node:crypto` (SHA-256). No third-party packages.
- *
- * Provenance: faithfully copied from
- *   github.com/Parad0x-Labs/dna-x402/tree/main/packages/context-capsule (MIT)
- * Excluded on purpose: searchCapsule, estimateSavings, intent tagging, and
- * anchorCorrectionChain (the latter is the only code path in the upstream
- * package that touches the network — it is intentionally NOT vendored here).
- */
-
-import { createHash } from "node:crypto";
-import { deflateSync } from "node:zlib";
-
-// ── Types ───────────────────────────────────────────────────────────────────
-
-export interface Message {
-  role: string;
-  content: string;
-}
-
-/** A compressed, auditable snapshot of an agent session's message history. */
-export interface ContextCapsule {
-  sessionId: string;
-  capsuleId: string;
-  originalTokenEstimate: number;
-  compressedBytes: number;
-  compressionRatio: string;
-  topics: string[];
-  merkleRoot: string;
-  createdAt: number;
-  compressedBase64: string;
-}
-
-export interface CompressOptions {
-  sessionId?: string;
-  maxOutputTokens?: number;
-}
-
-// ── Internal helpers ────────────────────────────────────────────────────────
-
-/** SHA-256 of a UTF-8 string → Buffer */
-function sha256(data: string): Buffer {
-  return createHash("sha256").update(data, "utf8").digest();
-}
-
-/**
- * Build a SHA-256 Merkle root over an ordered list of leaf buffers.
- * Empty → 32-byte zero buffer. Single leaf → that leaf. Odd node duplicates.
- */
-function buildMerkleRoot(leaves: Buffer[]): Buffer {
-  if (leaves.length === 0) return Buffer.alloc(32, 0);
-  if (leaves.length === 1) return leaves[0];
-
-  let level: Buffer[] = leaves;
-  while (level.length > 1) {
-    const next: Buffer[] = [];
-    for (let i = 0; i < level.length; i += 2) {
-      const left = level[i];
-      const right = i + 1 < level.length ? level[i + 1] : level[i]; // duplicate odd
-      next.push(createHash("sha256").update(left).update(right).digest());
-    }
-    level = next;
-  }
-  return level[0];
-}
-
-/** Extract up to `maxTopics` noun-phrase-like tokens from message text. */
-function extractTopics(messages: Message[], maxTopics = 5): string[] {
-  const allText = messages.map((m) => m.content).join(" ");
-
-  const titlePhrases = allText.match(/\b[A-Z][a-z]+(?:\s+[A-Z][a-z]+){1,3}\b/g) ?? [];
-  const properNouns = allText.match(/\b[A-Z][a-zA-Z]{3,}\b/g) ?? [];
-
-  const stopWords = new Set([
-    "the", "and", "for", "that", "this", "with", "have", "from", "they", "will",
-    "been", "were", "what", "when", "where", "which", "while", "about", "above",
-    "after", "before", "between", "through", "during", "because", "should",
-  ]);
-  const plainWords =
-    allText
-      .toLowerCase()
-      .match(/\b[a-z]{7,}\b/g)
-      ?.filter((w) => !stopWords.has(w)) ?? [];
-
-  const seen = new Set<string>();
-  const topics: string[] = [];
-  for (const raw of [...titlePhrases, ...properNouns, ...plainWords]) {
-    const key = raw.toLowerCase();
-    if (!seen.has(key)) {
-      seen.add(key);
-      topics.push(raw);
-      if (topics.length >= maxTopics) break;
-    }
-  }
-  return topics;
-}
-
-/** Deterministic capsule ID: sha256(sessionId + createdAt + merkleRoot) */
-function buildCapsuleId(sessionId: string, createdAt: number, merkleRoot: string): string {
-  return createHash("sha256")
-    .update(`${sessionId}:${createdAt}:${merkleRoot}`)
-    .digest("hex")
-    .slice(0, 32);
-}
-
-/** Estimate token count from character length (chars / 4 approximation) */
-function estimateTokens(text: string): number {
-  return Math.ceil(text.length / 4);
-}
-
-// ── Public API (subset) ──────────────────────────────────────────────────────
-
-/**
- * Compress a session's message history into a ContextCapsule.
- * Pure function — zlib deflate + SHA-256 only, no I/O.
- */
-export function compressContext(messages: Message[], opts: CompressOptions = {}): ContextCapsule {
-  if (!messages || messages.length === 0) {
-    throw new Error("compressContext: messages must be a non-empty array");
-  }
-
-  const sessionId = opts.sessionId ?? `session_${Date.now()}`;
-  const createdAt = Date.now();
-
-  const jsonl = messages.map((m) => JSON.stringify(m)).join("\n");
-  const compressed = deflateSync(Buffer.from(jsonl, "utf8"), { level: 9 });
-  const compressedBase64 = compressed.toString("base64");
-
-  const originalTokenEstimate = estimateTokens(jsonl);
-  const originalBytes = Buffer.byteLength(jsonl, "utf8");
-  const compressedBytes = compressed.length;
-  const compressionRatio = `${(originalBytes / compressedBytes).toFixed(1)}x`;
-
-  const topics = extractTopics(messages);
-
-  const leaves = messages.map((m) => sha256(JSON.stringify(m)));
-  const merkleRoot = buildMerkleRoot(leaves).toString("hex");
-  const capsuleId = buildCapsuleId(sessionId, createdAt, merkleRoot);
-
-  return {
-    sessionId,
-    capsuleId,
-    originalTokenEstimate,
-    compressedBytes,
-    compressionRatio,
-    topics,
-    merkleRoot,
-    createdAt,
-    compressedBase64,
-  };
-}
-
-/**
- * Generate a compact (~60–100 token) injection string that replaces full
- * history in an LLM call. Pure string builder — no I/O.
- */
-export function injectCapsule(capsule: ContextCapsule): string {
-  const topicList = capsule.topics.length > 0 ? capsule.topics.join(", ") : "general conversation";
-  const rootShort = capsule.merkleRoot.slice(0, 12);
-  return (
-    `[CONTEXT CAPSULE: session ${capsule.sessionId} compressed ${capsule.compressionRatio}. ` +
-    `Key topics: ${topicList}. ` +
-    `Merkle: ${rootShort}... ` +
-    `Full history available on request.]`
-  );
-}