@parad0x_labs/openclaw-context-capsule 1.4.0 → 1.7.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## 1.7.0
+
+- **Value-atom preservation.** A lone distinctive value — a bare port (`5433`), an
+  issue ref (`#4821`), a version (`v2.13.0`), an ISO date, or a hyphenated code
+  (`NEEDLE-ZX-7742`) — is now emitted as its own dense atom, so it survives
+  compression even when its surrounding sentence loses the budget race. Previously
+  such a value only survived when its whole line was selected. New regression:
+  `test/value-survival.test.mjs` (wired into `npm test`).
+- **Docs accuracy.** Corrected the documented config defaults (`maxCapsuleTokens`
+  `700` → `1400`, `capsuleTokenRatio` `0.08` → `0.14`) to match the shipped values.
+  Reframed the fidelity figures to state plainly that they are measured on the
+  maintainer's own private sessions via `test/fidelity-bench.mjs` (reproduce on your
+  own `~/.openclaw` sessions), not a repo fixture. The supersession clean rate (83%
+  floor) and value-survival remain CI-gated by `npm test`.
+
+## 1.6.0
+
+- Self-contained compression core bundled in `src/compression.ts` (no external
+  runtime dependency; no network / file-system / on-chain calls).

package/README.md

@@ -1,59 +1,31 @@
 # context-capsule — OpenClaw ContextEngine plugin
 
-> 💜 **Saving you tokens?** [Star it on ClawHub](https://clawhub.ai/parad0x-labs/context-capsule) — it's a context engine, so it works silently in the background. A star is the only way other agent builders find it.
-
-Compresses agent session history before it reaches the LLM. **Self-contained:**
-the compression core is vendored inline (`src/compression.ts`) — no external
-runtime dependency, and no network, file-system, or on-chain access. It uses
-only Node's built-in `zlib` and `crypto`.
-
-Sessions under 20 messages pass through unchanged. Longer sessions have their
-older history compressed into a capsule summary (injected as a system message)
-while the last 10 messages are kept verbatim — giving the model full coherence
-on recent turns without paying for the full transcript.
-
-> **Before you use this skill — read these:**
->
-> - **All messages are vault-scanned** for secrets and PII on every path (short
->   sessions, verbatim tail, and compressed history alike). Matched values are
->   replaced with typed placeholders. However, the vault scan covers common
->   patterns — it is not a guarantee that all sensitive content is removed.
->   Do not rely on it as the sole protection for highly sensitive sessions.
->
-> - **Compression alters history fidelity.** Older messages are summarised, not
->   preserved verbatim. Detail, nuance, and exact wording can be lost. Do not
->   use this skill where exact transcript fidelity is required.
->
-> - **Compressed history is injected as a system message.** This places
->   summarised content in a privileged prompt position. Be aware that prior
->   user/assistant content will influence the model from the system role after
->   compression.
->
-> - **No external runtime dependency.** The compression core is vendored inline
->   (`src/compression.ts`), so there is nothing external to resolve or verify.
->   The standalone `@parad0x_labs/context-capsule` library on npm is optional and
->   only relevant for non-OpenClaw use.
-
-**Most useful for:** local models (Ollama, LM Studio) and GPT-4 where context
-cost matters. Claude users with a 200k context window and built-in compaction
-enabled may not need this.
-
-## Benchmark
-
-| Metric | Result | CI gate |
-|---|---|---|
-| Token savings | 99.3% | >= 95% |
-| Recovery score | 100% | >= 90% |
-| Runtime | 29ms | < 1000ms |
-
-Reproduce locally:
+Self-contained OpenClaw context engine that reduces prompt tokens in long agent
+sessions. It keeps the recent tail verbatim and converts older history into a
+bounded, model-readable extractive capsule.
 
-```sh
-cd packages/context-capsule
-npm run bench:public
-```
+The capsule preserves high-value older context:
+
+- decisions and constraints
+- open tasks and requested work
+- errors and failed attempts
+- files, commands, and links
+- open questions and durable facts
+
+It also keeps a zlib-compressed payload and Merkle root for auditability, but the
+LLM is given the extractive capsule, not opaque compressed bytes.
 
-CI fails if savings drop below 95% or recovery falls below 90%.
+## Safety and limits
+
+- **Lossy by design.** Older messages are not preserved verbatim in the model
+  prompt. Exact wording, nuance, and low-priority details can be lost.
+- **Recent context remains verbatim.** `keepRecentMessages` controls how many
+  latest messages stay untouched.
+- **Best-effort vault scan.** Text content is scanned for common secrets and PII
+  before compression or model injection. This is useful defense-in-depth, not a
+  formal guarantee.
+- **No external runtime dependency.** The plugin uses only Node built-ins
+  (`zlib` and `crypto`) and makes no network, file-system, or on-chain calls.
 
 ## Activation
 
@@ -71,19 +43,45 @@ CI fails if savings drop below 95% or recovery falls below 90%.
 ## Config options
 
 | Key | Default | Description |
-|---|---|---|
-| `minMessages` | `20` | Sessions shorter than this pass through unchanged |
-| `keepRecentMessages` | `10` | Recent messages kept verbatim after compression |
+| --- | ---: | --- |
+| `minMessages` | `20` | Sessions shorter than this pass through unchanged. |
+| `keepRecentMessages` | `10` | Recent messages kept verbatim after compression. |
+| `maxCapsuleTokens` | `1400` | Hard cap for the injected extractive capsule. |
+| `capsuleTokenRatio` | `0.14` | If OpenClaw provides a model token budget, cap the capsule to this fraction of the budget. |
+| `minCompressTokens` | `900` | Estimated transcript-token floor before compression activates. |
 
 ```jsonc
 {
   "plugins": {
     "entries": {
       "context-capsule": {
-        "minMessages": 15,
-        "keepRecentMessages": 8
+        "minMessages": 20,
+        "keepRecentMessages": 10,
+        "maxCapsuleTokens": 1400,
+        "capsuleTokenRatio": 0.14,
+        "minCompressTokens": 900
       }
     }
   }
 }
 ```
+
+## Packaging
+
+The npm/ClawHub package ships compiled `dist/` JavaScript. It does not require
+TypeScript support from the host runtime.
+
+```sh
+npm run typecheck
+npm test
+npm pack --dry-run
+```
+
+## When to use
+
+Use this for long-running local or hosted model sessions where resending the full
+conversation is too expensive or pushes the model toward context overflow.
+
+Do not use it for workflows where old transcript wording must remain exact. For
+that, keep normal OpenClaw history or use a retrieval system that can quote the
+original source.

package/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: context-capsule
+description: Compresses older OpenClaw agent session history into a bounded, lane-change-aware context capsule — keeps recent messages verbatim, flags abandoned directions, quarantines injected instructions, and redacts secrets. Local, deterministic, any model.
+license: MIT
+metadata:
+  author: Parad0x-Labs
+---
+
+# Context Capsule
+
+Compress older agent session history before it hits the LLM, so long chats stop
+re-sending the full transcript every turn. It keeps the recent tail verbatim and
+turns older history into a bounded extractive capsule with decisions, tasks,
+errors, paths, links, questions, and durable facts. Works with any model —
+Claude, GPT, Ollama, Mistral, LM Studio.
+
+**What sets it apart:**
+
+- **Lane-change aware.** When the session pivots ("replace X with Y", "forget X,
+  use Y instead"), the capsule marks the abandoned direction as superseded and
+  keeps the live one — so the model never wanders back into a dropped plan. On a
+  held-out pivot set it cleans 83% of abandoned subjects with **zero** wrongly
+  flagged live choices.
+- **High fidelity per token.** Distinctive signals — file paths, IDs, ports,
+  URLs, commands, errors, decisions — are emitted as dense atoms. As of **v1.7.0**,
+  a lone value (a bare port `5433`, an issue ref `#4821`, a version `v2.13.0`, an
+  ISO date, a hyphenated code like `NEEDLE-ZX-7742`) is emitted as its **own** atom,
+  so it survives compression even when its surrounding sentence loses the budget
+  race — CI-tested in `test/value-survival.test.mjs`. On the maintainer's own real
+  sessions the capsule kept ~79% of key signals at ~5× reduction and ~93% at ~3.4×;
+  `test/fidelity-bench.mjs` measures this against **your own** `~/.openclaw` sessions
+  (run it on your data to reproduce — the figures are from private sessions, not a
+  repo fixture).
+
+> **Self-contained (v1.7.0):** The compression core is bundled directly in this
+> skill (`src/compression.ts`). There is **no external runtime dependency**, and
+> the plugin makes **no network, file-system, or on-chain calls**. Everything
+> runs locally using only Node's built-in `zlib` and `crypto`, and is fully
+> deterministic. Capsules carry a `schema` tag (`context-capsule.v2`).
+
+> **Protections (defense-in-depth, all CI-gated by `npm test`):**
+> - **Secret redaction (every surface).** API keys (OpenAI, Anthropic, AWS,
+>   Google, GitHub classic + fine-grained, GitLab, npm, Slack, Stripe, SendGrid,
+>   Twilio), JWTs, PEM blocks, URL basic-auth, `DATABASE_URL=` DSNs, and
+>   `key=value` credentials are detected by prefix/shape/context — never by raw
+>   entropy, so public IDs (git SHAs, UUIDs, chain addresses) are untouched.
+>   Redaction runs **before compression**, so no secret survives even in the zlib
+>   audit blob, and again on output — the core never emits a secret even if called
+>   directly. Each redaction carries a one-way **SHA-256 fingerprint**
+>   (`[REDACTED_AWS_KEY#a1b2c3d4]`) so the same key is correlatable across turns
+>   without ever exposing its value. Best-effort pattern matching — strong, not a
+>   guarantee for the most sensitive chats.
+> - **Injection quarantine** — instruction-injection patterns in older history
+>   ("ignore previous instructions", "you are now…", "reveal your prompt") are
+>   wrapped as inert untrusted text, never surfaced as a live instruction.
+> - **Bounded work** — every extraction pass runs on size-capped input, so a
+>   megabyte message or an adversarial string finishes in milliseconds instead of
+>   hanging the turn.
+
+## When to use
+
+- Long-running agent sessions (default: more than 20 messages) where the
+  transcript is large and you want to cut per-call token cost.
+- Any model/provider — local or hosted.
+
+## When NOT to use
+
+- Sessions that require **exact, verbatim transcript fidelity**. Older history is
+  summarized into a compact capsule; detail and nuance can be lost. Only the most
+  recent 10 messages are kept verbatim.
+- As your only safeguard for secrets/PII. The vault scan is best-effort, and the
+  compressed history is injected into the **system** context position.
+
+## How it works
+
+Keeps the last 10 messages verbatim by default. Older history is zlib-compressed
+for auditability, then converted into a model-readable extractive capsule. The
+model sees compact sections for decisions/constraints, tasks, errors, files,
+commands, links, questions, and durable facts. The capsule is capped by
+`maxCapsuleTokens` and adapts to the host token budget with
+`capsuleTokenRatio`.
+
+## Savings
+
+|                       | Without | With     |
+| --------------------- | ------- | -------- |
+| Prompt history sent   | Full transcript | Capsule + recent tail |
+| Compression trigger   | N/A     | Message + token threshold |
+| Runtime dependencies  | N/A     | Node built-ins only |
+
+## Install
+
+This skill is self-contained — no extra packages to install. Register it as your
+context engine in `openclaw.json`:
+
+```jsonc
+{
+  "plugins": {
+    "slots": { "contextEngine": "context-capsule" }
+  }
+}
+```
+
+Optional config (defaults shown):
+
+```jsonc
+{
+  "plugins": {
+    "entries": {
+      "context-capsule": {
+        "minMessages": 20,
+        "keepRecentMessages": 10,
+        "maxCapsuleTokens": 1400,
+        "capsuleTokenRatio": 0.14,
+        "minCompressTokens": 900
+      }
+    }
+  }
+}
+```
+
+## Source
+
+github.com/Parad0x-Labs/openclaw-skills/tree/main/skills/context-capsule
+
+The standalone library (`@parad0x_labs/context-capsule`) is published separately
+on npm for non-OpenClaw use; this skill vendors only the two pure functions it
+needs and does not depend on it at runtime.
+
+---
+
+💜 If Context Capsule is quietly shrinking your token bill, a ⭐ on ClawHub helps
+other agent builders find it.
+

package/dist/compression.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Self-contained compression core for the Context Capsule skill.
+ *
+ * The model cannot use opaque zlib bytes directly, so this module stores the
+ * compressed payload for auditability but injects a bounded extractive capsule:
+ * decisions, tasks, errors, paths, URLs, questions, and durable facts selected
+ * from older history. This is still lossy, but it preserves the material that
+ * usually matters in long agent sessions while keeping prompt tokens bounded.
+ *
+ * Crypto/compression run through a platform shim (./platform): the Node build
+ * uses `node:zlib` + `node:crypto`; a browser build aliases it to
+ * ./platform.browser (@noble/hashes + pako) so this exact source also runs in a
+ * browser tab. The SHA-256 path is byte-identical across backends, so a capsule's
+ * merkleRoot / capsuleId / injected memory are identical in a browser and in Node
+ * (the audit blob is round-trip-identical) — see test/platform-parity.test.mjs.
+ * No network, file I/O, or dynamic imports.
+ */
+export interface Message {
+    role: string;
+    content: string;
+}
+export type CapsuleFactKind = "decision" | "task" | "error" | "file" | "question" | "fact";
+export interface CapsuleFact {
+    kind: CapsuleFactKind;
+    text: string;
+    role: string;
+    sourceIndex: number;
+    score: number;
+}
+/** A compressed, auditable snapshot of an agent session's message history. */
+export interface ContextCapsule {
+    /** Schema/version tag for forward-compatibility (e.g. "context-capsule.v2"). */
+    schema: string;
+    sessionId: string;
+    capsuleId: string;
+    originalTokenEstimate: number;
+    compressedBytes: number;
+    compressionRatio: string;
+    topics: string[];
+    facts: CapsuleFact[];
+    /** Subjects a later turn abandoned/replaced; surfaced as superseded. */
+    superseded: string[];
+    droppedFactCount: number;
+    maxOutputTokens: number;
+    merkleRoot: string;
+    createdAt: number;
+    compressedBase64: string;
+}
+export interface CompressOptions {
+    sessionId?: string;
+    maxOutputTokens?: number;
+    maxFacts?: number;
+}
+export interface InjectOptions {
+    maxOutputTokens?: number;
+}
+/**
+ * Compress a session's message history into a ContextCapsule.
+ * Pure function — extractive capsule + zlib deflate + SHA-256 only, no I/O.
+ */
+export declare function compressContext(messages: Message[], opts?: CompressOptions): ContextCapsule;
+/**
+ * Generate a bounded injection string that replaces full older history in an
+ * LLM call. The output intentionally contains useful extracted facts, not the
+ * opaque compressed payload.
+ */
+export declare function injectCapsule(capsule: ContextCapsule, opts?: InjectOptions): string;