npm - @vainplex/openclaw-cortex - Versions diffs - 0.4.0 → 0.4.1 - Mend

@vainplex/openclaw-cortex 0.4.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/README.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # @vainplex/openclaw-cortex
-> Conversation intelligence layer for [OpenClaw](https://github.com/openclaw/openclaw) — automated thread tracking, decision extraction, boot context generation, and pre-compaction snapshots.
+> Conversation intelligence layer for [OpenClaw](https://github.com/openclaw/openclaw) — automated thread tracking, decision extraction, boot context generation, pre-compaction snapshots, and trace analysis.
 [![npm](https://img.shields.io/npm/v/@vainplex/openclaw-cortex)](https://www.npmjs.com/package/@vainplex/openclaw-cortex)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -14,6 +14,7 @@
 - **🚀 Generates boot context** — assembles a dense `BOOTSTRAP.md` at session start so the agent has continuity
 - **📸 Pre-compaction snapshots** — saves thread state + hot snapshot before memory compaction
 - **📖 Structured narratives** — generates 24h activity summaries from threads + decisions
+- **🔍 Trace Analyzer** — 3-stage pipeline that detects failure signals, classifies findings with LLM triage, and generates PII-redacted reports
 Works **alongside** `memory-core` (OpenClaw's built-in memory) — doesn't replace it.
@@ -393,11 +394,108 @@ The LLM sees a conversation snippet (configurable batch size) and returns:
 - Hook errors → caught and logged, never crashes the gateway
 - LLM timeout/error → falls back to regex-only, no data loss
+## Trace Analyzer (v0.4.0)
+The Trace Analyzer is a **3-stage pipeline** that processes NATS event streams to detect failure patterns in AI agent conversations. It reconstructs conversation chains, runs signal detection, classifies findings with an optional LLM triage step, applies PII redaction, and generates structured reports.
+### 3-Stage Pipeline
+```
+Stage 1: Ingest + Reconstruct
+  NATS events → normalize → chain reconstruction (gap-based splitting)
+Stage 2: Signal Detection + Classification
+  chains → 7 signal detectors (multi-language) → LLM triage (optional) → classified findings
+Stage 3: Redaction + Output
+  findings → PII redaction → report assembly → Markdown/JSON output
+```
+### 7 Signal Detectors
+| Signal ID | Detects | Default |
+|-----------|---------|---------|
+| `SIG-CORRECTION` | User correcting the agent after a wrong response | ✅ enabled |
+| `SIG-TOOL-FAIL` | Tool/function call failures and error responses | ✅ enabled |
+| `SIG-DOOM-LOOP` | Agent stuck in repetitive retry loops | ✅ enabled |
+| `SIG-DISSATISFIED` | User expressing frustration or dissatisfaction | ✅ enabled |
+| `SIG-REPEAT-FAIL` | Same failure pattern recurring across sessions | ✅ enabled |
+| `SIG-HALLUCINATION` | Agent making claims contradicted by tool output | ✅ enabled |
+| `SIG-UNVERIFIED-CLAIM` | Agent stating facts without tool verification | ❌ disabled |
+Each detector supports **multi-language signal patterns** — the same 10 languages as the core pattern engine (EN, DE, FR, ES, PT, IT, ZH, JA, KO, RU).
+### Configuration
+Add a `traceAnalyzer` section to your external config (`~/.openclaw/plugins/openclaw-cortex/config.json`):
+```json
+{
+  "traceAnalyzer": {
+    "enabled": true,
+    "nats": {
+      "url": "nats://localhost:4222",
+      "stream": "openclaw-events",
+      "subjectPrefix": "openclaw.events"
+    },
+    "schedule": {
+      "enabled": true,
+      "intervalHours": 24
+    },
+    "signals": {
+      "SIG-UNVERIFIED-CLAIM": { "enabled": true, "severity": "medium" }
+    },
+    "llm": {
+      "enabled": true,
+      "endpoint": "http://localhost:11434/v1",
+      "model": "mistral:7b"
+    },
+    "output": {
+      "maxFindings": 200,
+      "reportPath": "./reports/trace-analysis.md"
+    },
+    "redactPatterns": ["\\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Z|a-z]{2,}\\b"]
+  }
+}
+```
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `enabled` | `false` | Master switch for trace analysis |
+| `nats.url` | `nats://localhost:4222` | NATS server URL |
+| `nats.stream` | `openclaw-events` | JetStream stream name |
+| `schedule.enabled` | `false` | Enable scheduled analysis runs |
+| `schedule.intervalHours` | `24` | Hours between runs |
+| `chainGapMinutes` | `30` | Inactivity gap for chain boundary detection |
+| `llm.enabled` | `false` | Enable LLM-powered finding classification |
+| `llm.triage` | — | Optional fast/local model for pre-filtering |
+| `output.maxFindings` | `200` | Maximum findings per report |
+| `output.reportPath` | — | Custom report output path |
+| `redactPatterns` | `[]` | Regex patterns for PII redaction |
+### Programmatic API
+The trace analyzer is fully exported for programmatic use:
+```typescript
+import {
+  TraceAnalyzer,
+  createNatsTraceSource,
+  reconstructChains,
+  detectAllSignals,
+  classifyFindings,
+  redactChain,
+  assembleReport,
+  generateOutputs,
+  resolveTraceAnalyzerConfig,
+} from "@vainplex/openclaw-cortex";
+```
 ## Development
 ```bash
 npm install
-npm test            # 516 tests
+npm test            # 850 tests
 npm run typecheck   # TypeScript strict mode
 npm run build       # Compile to dist/
 ```
@@ -409,7 +507,7 @@ npm run build       # Compile to dist/
 - LLM enhancement: async, batched, fire-and-forget (never blocks hooks)
 - Atomic file writes via `.tmp` + rename
 - Noise filter prevents garbage threads from polluting state
-- Tested with 516 unit + integration tests
+- Tested with 850 unit + integration tests
 ## Architecture
@@ -426,6 +524,6 @@ All plugins live in one monorepo: [alberthild/vainplex-openclaw](https://github.
 | # | Plugin | Version | Description |
 |---|--------|---------|-------------|
 | 1 | [@vainplex/nats-eventstore](https://github.com/alberthild/vainplex-openclaw/tree/main/packages/openclaw-nats-eventstore) | 0.2.1 | NATS JetStream event persistence + audit trail |
-| 2 | **@vainplex/openclaw-cortex** | **0.3.1** | Conversation intelligence — threads, decisions, boot context, 10 languages (this plugin) |
-| 3 | [@vainplex/openclaw-knowledge-engine](https://github.com/alberthild/vainplex-openclaw/tree/main/packages/openclaw-knowledge-engine) | 0.1.3 | Real-time fact extraction from conversations |
-| 4 | [@vainplex/openclaw-governance](https://github.com/alberthild/vainplex-openclaw/tree/main/packages/openclaw-governance) | 0.3.1 | Policy-as-code — trust scoring, audit trail, production safeguards |
+| 2 | **@vainplex/openclaw-cortex** | **0.4.0** | Conversation intelligence — threads, decisions, boot context, trace analysis, 10 languages (this plugin) |
+| 3 | [@vainplex/openclaw-knowledge-engine](https://github.com/alberthild/vainplex-openclaw/tree/main/packages/openclaw-knowledge-engine) | 0.1.4 | Real-time fact extraction from conversations |
+| 4 | [@vainplex/openclaw-governance](https://github.com/alberthild/vainplex-openclaw/tree/main/packages/openclaw-governance) | 0.3.2 | Policy-as-code — trust scoring, audit trail, production safeguards |

package/dist/index.d.ts CHANGED Viewed

@@ -1,4 +1,5 @@
 import type { OpenClawPluginApi } from "./src/types.js";
+export * from "./src/trace-analyzer/index.js";
 declare const plugin: {
     id: string;
     name: string;

package/dist/index.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAe,MAAM,gBAAgB,CAAC;~~AAErE~~,QAAA,MAAM,MAAM;;;;;kBAOI,iBAAiB;CA8ChC,CAAC;AAEF,eAAe,MAAM,CAAC"}
1	+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAe,MAAM,gBAAgB,CAAC;AAGrE,cAAc,+BAA+B,CAAC;AAE9C,QAAA,MAAM,MAAM;;;;;kBAOI,iBAAiB;CA8ChC,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/dist/index.js CHANGED Viewed

@@ -2,6 +2,8 @@ import { registerCortexHooks } from "./src/hooks.js";
 import { resolveWorkspace } from "./src/config.js";
 import { loadConfig } from "./src/config-loader.js";
 import { loadJson, rebootDir } from "./src/storage.js";
+// ---- Trace Analyzer public API re-export ----
+export * from "./src/trace-analyzer/index.js";
 const plugin = {
     id: "openclaw-cortex",
     name: "OpenClaw Cortex",

package/dist/index.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAGvD,MAAM,MAAM,GAAG;IACb,EAAE,EAAE,iBAAiB;IACrB,IAAI,EAAE,iBAAiB;IACvB,WAAW,EACT,0GAA0G;IAC5G,OAAO,EAAE,OAAO;IAEhB,QAAQ,CAAC,GAAsB;QAC7B,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC,GAAG,CAAC,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;QAE5D,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,8BAA8B,CAAC,CAAC;YAChD,OAAO;QACT,CAAC;QAED,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,yDAAyD,CAAC,CAAC;QAE3E,6BAA6B;QAC7B,mBAAmB,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAEjC,iCAAiC;QACjC,GAAG,CAAC,eAAe,CAAC;YAClB,IAAI,EAAE,cAAc;YACpB,WAAW,EAAE,4DAA4D;YACzE,WAAW,EAAE,IAAI;YACjB,OAAO,EAAE,GAAG,EAAE;gBACZ,IAAI,CAAC;oBACH,MAAM,SAAS,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;oBAC3C,MAAM,IAAI,GAAG,QAAQ,CACnB,GAAG,SAAS,CAAC,SAAS,CAAC,eAAe,CACvC,CAAC;oBACF,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC;oBACnC,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,MAAM,CAAC;oBAClE,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,MAAM,CAAC;oBACtE,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,IAAI,SAAS,CAAC;oBAC5C,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC;oBAExC,OAAO;wBACL,IAAI,EAAE;4BACJ,mBAAmB;4BACnB,YAAY,SAAS,UAAU,WAAW,SAAS;4BACnD,SAAS,IAAI,EAAE;4BACf,YAAY,OAAO,EAAE;yBACtB,CAAC,IAAI,CAAC,IAAI,CAAC;qBACb,CAAC;gBACJ,CAAC;gBAAC,MAAM,CAAC;oBACP,OAAO,EAAE,IAAI,EAAE,4CAA4C,EAAE,CAAC;gBAChE,CAAC;YACH,CAAC;SACF,CAAC,CAAC;QAEH,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;IACpC,CAAC;CACF,CAAC;AAEF,eAAe,MAAM,CAAC"}
1	+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAGvD,gDAAgD;AAChD,cAAc,+BAA+B,CAAC;AAE9C,MAAM,MAAM,GAAG;IACb,EAAE,EAAE,iBAAiB;IACrB,IAAI,EAAE,iBAAiB;IACvB,WAAW,EACT,0GAA0G;IAC5G,OAAO,EAAE,OAAO;IAEhB,QAAQ,CAAC,GAAsB;QAC7B,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC,GAAG,CAAC,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;QAE5D,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,8BAA8B,CAAC,CAAC;YAChD,OAAO;QACT,CAAC;QAED,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,yDAAyD,CAAC,CAAC;QAE3E,6BAA6B;QAC7B,mBAAmB,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAEjC,iCAAiC;QACjC,GAAG,CAAC,eAAe,CAAC;YAClB,IAAI,EAAE,cAAc;YACpB,WAAW,EAAE,4DAA4D;YACzE,WAAW,EAAE,IAAI;YACjB,OAAO,EAAE,GAAG,EAAE;gBACZ,IAAI,CAAC;oBACH,MAAM,SAAS,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;oBAC3C,MAAM,IAAI,GAAG,QAAQ,CACnB,GAAG,SAAS,CAAC,SAAS,CAAC,eAAe,CACvC,CAAC;oBACF,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC;oBACnC,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,MAAM,CAAC;oBAClE,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,MAAM,CAAC;oBACtE,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,IAAI,SAAS,CAAC;oBAC5C,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC;oBAExC,OAAO;wBACL,IAAI,EAAE;4BACJ,mBAAmB;4BACnB,YAAY,SAAS,UAAU,WAAW,SAAS;4BACnD,SAAS,IAAI,EAAE;4BACf,YAAY,OAAO,EAAE;yBACtB,CAAC,IAAI,CAAC,IAAI,CAAC;qBACb,CAAC;gBACJ,CAAC;gBAAC,MAAM,CAAC;oBACP,OAAO,EAAE,IAAI,EAAE,4CAA4C,EAAE,CAAC;gBAChE,CAAC;YACH,CAAC;SACF,CAAC,CAAC;QAEH,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;IACpC,CAAC;CACF,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/openclaw.plugin.json CHANGED Viewed

@@ -146,10 +146,11 @@
             "enum": [
               "en",
               "de",
-              "both"
+              "both",
+              "all"
             ],
             "default": "both",
-            "description": "Language for regex pattern matching: English, German, or both"
+            "description": "Language for regex pattern matching: English, German, both, or all 10 languages"
           }
         }
       },
@@ -193,6 +194,187 @@
             "description": "Number of messages to buffer before calling the LLM"
           }
         }
+      },
+      "traceAnalyzer": {
+        "type": "object",
+        "additionalProperties": false,
+        "description": "Trace Analyzer — 3-stage pipeline for detecting failure signals in NATS event streams",
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "Master switch for trace analysis"
+          },
+          "nats": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "url": {
+                "type": "string",
+                "default": "nats://localhost:4222",
+                "description": "NATS server URL"
+              },
+              "stream": {
+                "type": "string",
+                "default": "openclaw-events",
+                "description": "JetStream stream name"
+              },
+              "subjectPrefix": {
+                "type": "string",
+                "default": "openclaw.events",
+                "description": "NATS subject prefix"
+              },
+              "credentials": {
+                "type": "string",
+                "description": "Optional NATS credentials file path"
+              },
+              "user": {
+                "type": "string",
+                "description": "Optional NATS user"
+              },
+              "password": {
+                "type": "string",
+                "description": "Optional NATS password"
+              }
+            }
+          },
+          "schedule": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "enabled": {
+                "type": "boolean",
+                "default": false,
+                "description": "Enable scheduled analysis runs"
+              },
+              "intervalHours": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 168,
+                "default": 24,
+                "description": "Hours between scheduled runs"
+              }
+            }
+          },
+          "chainGapMinutes": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 120,
+            "default": 30,
+            "description": "Inactivity gap in minutes for chain boundary detection"
+          },
+          "signals": {
+            "type": "object",
+            "description": "Per-signal toggles and severity overrides",
+            "additionalProperties": {
+              "type": "object",
+              "properties": {
+                "enabled": {
+                  "type": "boolean"
+                },
+                "severity": {
+                  "type": "string",
+                  "enum": ["low", "medium", "high", "critical"]
+                }
+              }
+            }
+          },
+          "llm": {
+            "type": "object",
+            "additionalProperties": false,
+            "description": "LLM config for trace analysis finding classification",
+            "properties": {
+              "enabled": {
+                "type": "boolean",
+                "default": false,
+                "description": "Enable LLM-powered finding classification"
+              },
+              "endpoint": {
+                "type": "string",
+                "description": "OpenAI-compatible API endpoint"
+              },
+              "model": {
+                "type": "string",
+                "description": "Model identifier"
+              },
+              "apiKey": {
+                "type": "string",
+                "description": "API key (optional)"
+              },
+              "timeoutMs": {
+                "type": "integer",
+                "minimum": 1000,
+                "maximum": 120000,
+                "description": "Timeout per LLM call in milliseconds"
+              },
+              "triage": {
+                "type": "object",
+                "additionalProperties": false,
+                "description": "Optional fast/local triage model for pre-filtering",
+                "properties": {
+                  "endpoint": {
+                    "type": "string"
+                  },
+                  "model": {
+                    "type": "string"
+                  },
+                  "apiKey": {
+                    "type": "string"
+                  },
+                  "timeoutMs": {
+                    "type": "integer",
+                    "minimum": 1000,
+                    "maximum": 60000
+                  }
+                }
+              }
+            }
+          },
+          "output": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "maxFindings": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 1000,
+                "default": 200,
+                "description": "Maximum findings in a single report"
+              },
+              "reportPath": {
+                "type": "string",
+                "description": "Custom report output path"
+              }
+            }
+          },
+          "redactPatterns": {
+            "type": "array",
+            "items": { "type": "string" },
+            "default": [],
+            "description": "Regex patterns for PII redaction before LLM/disk writes"
+          },
+          "incrementalContextWindow": {
+            "type": "integer",
+            "minimum": 50,
+            "maximum": 5000,
+            "default": 500,
+            "description": "Context window size for incremental processing"
+          },
+          "fetchBatchSize": {
+            "type": "integer",
+            "minimum": 10,
+            "maximum": 5000,
+            "default": 500,
+            "description": "NATS consumer batch size for fetching events"
+          },
+          "maxEventsPerRun": {
+            "type": "integer",
+            "minimum": 100,
+            "maximum": 1000000,
+            "default": 100000,
+            "description": "Maximum events to process per run"
+          }
+        }
       }
     }
   }

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "@vainplex/openclaw-cortex",
-  "version": "0.4.0",
-  "description": "OpenClaw plugin: conversation intelligence — thread tracking, decision extraction, boot context, pre-compaction snapshots",
+  "version": "0.4.1",
+  "description": "OpenClaw plugin: conversation intelligence — thread tracking, decision extraction, boot context, pre-compaction snapshots, trace analysis",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -37,7 +37,10 @@
     "memory",
     "thread-tracking",
     "boot-context",
-    "conversation-intelligence"
+    "conversation-intelligence",
+    "trace-analyzer",
+    "signal-detection",
+    "conversation-analysis"
   ],
   "license": "MIT",
   "repository": {
@@ -45,6 +48,6 @@
     "url": "https://github.com/alberthild/vainplex-openclaw.git",
     "directory": "packages/openclaw-cortex"
   },
-  "homepage": "https://github.com/alberthild/openclaw-cortex#readme",
+  "homepage": "https://github.com/alberthild/vainplex-openclaw/tree/main/packages/openclaw-cortex",
   "author": "Albert Hild <a.hild@vainplex.de>"
 }