@vainplex/nats-eventstore 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vainplex
+
+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.

package/README.md

@@ -0,0 +1,273 @@
+# @vainplex/openclaw-nats-eventstore
+
+OpenClaw plugin that publishes agent events to **NATS JetStream** for audit, replay, and multi-agent sharing.
+
+## Features
+
+- 🔄 **17 event types** — messages, tool calls, LLM I/O, sessions, gateway lifecycle
+- 🛡️ **Non-fatal** — event store failures never affect agent operations
+- 🔐 **Privacy-conscious** — LLM events log metadata (lengths, counts), not content
+- ⚡ **Fire-and-forget** — async publish with automatic error handling
+- 🔧 **Configurable** — include/exclude hooks, retention policies, custom subjects
+- 📡 **Auto-reconnect** — built-in NATS reconnection with status monitoring
+
+## Quick Start
+
+### 1. Install NATS Server
+
+**Docker (recommended):**
+```bash
+docker run -d --name nats \
+  -p 4222:4222 -p 8222:8222 \
+  nats:latest -js -m 8222
+```
+
+**macOS:** `brew install nats-server && nats-server -js`
+
+**Linux:**
+```bash
+curl -sf https://binaries.nats.dev/nats-io/nats-server/v2@latest | sh
+nats-server -js
+```
+
+The `-js` flag enables JetStream (required for event persistence).
+
+Verify it's running: `curl http://localhost:8222/healthz` → `{"status":"ok"}`
+
+### 2. Install the Plugin
+
+Run from your **OpenClaw extensions directory** (`~/.openclaw/extensions/`):
+
+```bash
+cd ~/.openclaw/extensions
+npm install @vainplex/openclaw-nats-eventstore
+```
+
+This installs the plugin where OpenClaw can discover it. Alternatively, create a symlink:
+
+```bash
+ln -s /path/to/node_modules/@vainplex/nats-eventstore ~/.openclaw/extensions/nats-eventstore
+```
+
+### 3. Configure & Restart
+
+Add the plugin to your `openclaw.json` (see Configuration below), then restart the gateway.
+
+### 4. Verify
+
+```bash
+# Install NATS CLI (optional, for debugging)
+# brew install nats-io/nats-tools/nats  OR  go install github.com/nats-io/natscli/nats@latest
+
+nats sub "openclaw.events.>"
+# Send a message to your agent — you should see events flowing
+```
+
+## Configuration
+
+Add to the `plugins.entries` section of your `openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "nats-eventstore": {
+        "enabled": true,
+        "config": {
+          "enabled": true,
+          "natsUrl": "nats://localhost:4222",
+          "streamName": "openclaw-events",
+          "subjectPrefix": "openclaw.events",
+          "retention": {
+            "maxMessages": -1,
+            "maxBytes": -1,
+            "maxAgeHours": 720
+          },
+          "publishTimeoutMs": 5000,
+          "connectTimeoutMs": 5000,
+          "drainTimeoutMs": 5000,
+          "excludeHooks": ["message_sending"]
+        }
+      }
+    }
+  }
+}
+```
+
+### Config Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | boolean | `true` | Enable/disable event publishing |
+| `natsUrl` | string | `nats://localhost:4222` | NATS server URL (supports `nats://user:pass@host:port`) |
+| `streamName` | string | `openclaw-events` | JetStream stream name |
+| `subjectPrefix` | string | `openclaw.events` | Subject prefix for all events |
+| `retention.maxMessages` | integer | `-1` | Max messages to retain (-1 = unlimited) |
+| `retention.maxBytes` | integer | `-1` | Max bytes to retain (-1 = unlimited) |
+| `retention.maxAgeHours` | number | `0` | Max age in hours (0 = unlimited) |
+| `publishTimeoutMs` | integer | `5000` | Timeout for publish operations |
+| `connectTimeoutMs` | integer | `5000` | Timeout for initial connection |
+| `drainTimeoutMs` | integer | `5000` | Timeout for graceful drain |
+| `includeHooks` | string[] | `[]` | Whitelist of hooks to publish (empty = all) |
+| `excludeHooks` | string[] | `[]` | Blacklist of hooks to skip |
+
+### Authentication
+
+Include credentials in the NATS URL:
+
+```json
+"natsUrl": "nats://myuser:mypassword@nats.example.com:4222"
+```
+
+Credentials are stripped from log output automatically.
+
+## Event Types
+
+| OpenClaw Hook | NATS Event Type | Subject Suffix |
+|---|---|---|
+| `message_received` | `msg.in` | `msg_in` |
+| `message_sent` | `msg.out` | `msg_out` |
+| `message_sending` | `msg.sending` | `msg_sending` |
+| `before_tool_call` | `tool.call` | `tool_call` |
+| `after_tool_call` | `tool.result` | `tool_result` |
+| `before_agent_start` | `run.start` | `run_start` |
+| `agent_end` | `run.end` | `run_end` |
+| `agent_end` (failure) | `run.error` | `run_error` |
+| `llm_input` | `llm.input` | `llm_input` |
+| `llm_output` | `llm.output` | `llm_output` |
+| `before_compaction` | `session.compaction_start` | `session_compaction_start` |
+| `after_compaction` | `session.compaction_end` | `session_compaction_end` |
+| `before_reset` | `session.reset` | `session_reset` |
+| `session_start` | `session.start` | `session_start` |
+| `session_end` | `session.end` | `session_end` |
+| `gateway_start` | `gateway.start` | `gateway_start` |
+| `gateway_stop` | `gateway.stop` | `gateway_stop` |
+
+## NATS Subject Schema
+
+```
+{subjectPrefix}.{agentId}.{eventType}
+```
+
+Examples:
+```
+openclaw.events.main.msg_in
+openclaw.events.viola.tool_call
+openclaw.events.system.gateway_start
+openclaw.events.*.msg_in          # wildcard: all agents
+openclaw.events.>                 # all events
+```
+
+## Event Envelope
+
+Every event follows this structure:
+
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "ts": 1739734800000,
+  "agent": "main",
+  "session": "main:matrix:albert",
+  "type": "msg.in",
+  "payload": {
+    "from": "albert",
+    "content": "Hello!"
+  }
+}
+```
+
+## Commands
+
+### `/eventstatus`
+
+Shows current NATS connection status:
+
+```
+NATS Event Store
+Connected: ✅
+Stream: openclaw-events
+Disconnects: 0
+Publish failures: 0
+```
+
+## Gateway Method
+
+```typescript
+// Programmatic status check
+const status = await gateway.call("eventstore.status");
+// { connected: true, stream: "openclaw-events", disconnectCount: 0, publishFailures: 0 }
+```
+
+## Subscribing to Events
+
+Use the NATS CLI or any NATS client to subscribe:
+
+```bash
+# All events
+nats sub "openclaw.events.>"
+
+# All events for a specific agent
+nats sub "openclaw.events.main.>"
+
+# Only message events
+nats sub "openclaw.events.*.msg_*"
+
+# Only tool calls
+nats sub "openclaw.events.*.tool_call"
+```
+
+## Migration from Core Event Store (PR #18171)
+
+If you were using the core event store:
+
+1. Install this plugin
+2. Move config from `"eventStore"` to `"plugins" → "entries" → "nats-eventstore" → "config"`
+3. Remove the `"eventStore"` section from `openclaw.json`
+4. Restart the gateway
+
+The plugin publishes to the **same NATS subjects and stream** — existing consumers continue working.
+
+## Performance
+
+Benchmark results on a single-node NATS v2.12 server (JetStream, file storage, commodity hardware):
+
+| Test | Throughput | Latency (p99) |
+|------|-----------|---------------|
+| Sequential publish | ~3,800 msg/s | 0.4ms |
+| Concurrent (10 workers) | ~9,000 msg/s | 2.9ms |
+| Multi-subject fan-out (56 subjects) | ~9,000 msg/s | — |
+| Consumer read | ~20,000 msg/s | — |
+| Sustained (15s continuous) | ~3,800 msg/s | — |
+
+**Payload scaling:**
+
+| Payload size | Throughput | Data rate |
+|-------------|-----------|-----------|
+| 100 B | ~4,000 msg/s | 390 KB/s |
+| 1 KB | ~3,500 msg/s | 3.3 MB/s |
+| 10 KB | ~2,600 msg/s | 25 MB/s |
+| 50 KB | ~1,600 msg/s | 77 MB/s |
+
+Typical OpenClaw event payloads are 200–500 bytes. At normal agent usage (~50–100 events/min), the plugin uses less than 1% of available throughput. Zero errors across all benchmark runs.
+
+A benchmark script is included in the repository — see `scripts/nats-benchmark.mjs` (note: lives in the [companion workspace](https://git.vainplex.dev/claudia.keller/claudia-workspace), not this package).
+
+## Development
+
+```bash
+# Run tests
+npm test
+
+# Run with integration tests (requires NATS on localhost:14222)
+NATS_URL=nats://localhost:14222 npm test
+
+# Watch mode
+npm run test:watch
+
+# Type check
+npm run typecheck
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+import type { PluginLogger } from "./src/nats-client.js";
+type OpenClawPluginApi = {
+    id: string;
+    pluginConfig?: Record<string, unknown>;
+    logger: PluginLogger;
+    config: Record<string, unknown>;
+    registerService: (service: {
+        id: string;
+        start: (ctx: any) => Promise<void>;
+        stop: (ctx: any) => Promise<void>;
+    }) => void;
+    registerCommand: (command: Record<string, unknown>) => void;
+    registerGatewayMethod: (method: string, handler: (...args: any[]) => any) => void;
+    on: (hookName: string, handler: (...args: any[]) => void, opts?: {
+        priority?: number;
+    }) => void;
+};
+declare const plugin: {
+    id: string;
+    name: string;
+    description: string;
+    version: string;
+    register(api: OpenClawPluginApi): void;
+};
+export default plugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAKzD,KAAK,iBAAiB,GAAG;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,eAAe,EAAE,CAAC,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;QAAC,IAAI,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,KAAK,IAAI,CAAC;IAC1H,eAAe,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IAC5D,qBAAqB,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,KAAK,IAAI,CAAC;IAClF,EAAE,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CACjG,CAAC;AAIF,QAAA,MAAM,MAAM;;;;;kBAMI,iBAAiB;CAqDhC,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/dist/index.js

@@ -0,0 +1,55 @@
+import { createEventStoreService } from "./src/service.js";
+import { registerEventHooks } from "./src/hooks.js";
+import { resolveConfig } from "./src/config.js";
+let client = null;
+const plugin = {
+    id: "nats-eventstore",
+    name: "NATS Event Store",
+    description: "Publish agent events to NATS JetStream for audit, replay, and multi-agent sharing",
+    version: "0.1.0",
+    register(api) {
+        const config = resolveConfig(api.pluginConfig);
+        if (!config.enabled) {
+            api.logger.info("[nats-eventstore] Disabled via config");
+            return;
+        }
+        // Register service for connection lifecycle
+        api.registerService(createEventStoreService(() => client, (c) => { client = c; }));
+        // Register all hook handlers
+        registerEventHooks(api, config, () => client);
+        // Register /eventstatus command
+        api.registerCommand({
+            name: "eventstatus",
+            description: "Show NATS event store connection status",
+            requireAuth: true,
+            handler: () => {
+                const status = client?.getStatus() ?? {
+                    connected: false,
+                    stream: null,
+                    disconnectCount: 0,
+                    publishFailures: 0,
+                };
+                return {
+                    text: [
+                        "**NATS Event Store**",
+                        `Connected: ${status.connected ? "✅" : "❌"}`,
+                        `Stream: ${status.stream ?? "n/a"}`,
+                        `Disconnects: ${status.disconnectCount}`,
+                        `Publish failures: ${status.publishFailures}`,
+                    ].join("\n"),
+                };
+            },
+        });
+        // Register gateway method for programmatic status
+        api.registerGatewayMethod("eventstore.status", async () => {
+            return client?.getStatus() ?? {
+                connected: false,
+                stream: null,
+                disconnectCount: 0,
+                publishFailures: 0,
+            };
+        });
+    },
+};
+export default plugin;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAahD,IAAI,MAAM,GAAsB,IAAI,CAAC;AAErC,MAAM,MAAM,GAAG;IACb,EAAE,EAAE,iBAAiB;IACrB,IAAI,EAAE,kBAAkB;IACxB,WAAW,EAAE,mFAAmF;IAChG,OAAO,EAAE,OAAO;IAEhB,QAAQ,CAAC,GAAsB;QAC7B,MAAM,MAAM,GAAG,aAAa,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;QAE/C,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,uCAAuC,CAAC,CAAC;YACzD,OAAO;QACT,CAAC;QAED,4CAA4C;QAC5C,GAAG,CAAC,eAAe,CACjB,uBAAuB,CACrB,GAAG,EAAE,CAAC,MAAM,EACZ,CAAC,CAAC,EAAE,EAAE,GAAG,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CACvB,CACF,CAAC;QAEF,6BAA6B;QAC7B,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC;QAE9C,gCAAgC;QAChC,GAAG,CAAC,eAAe,CAAC;YAClB,IAAI,EAAE,aAAa;YACnB,WAAW,EAAE,yCAAyC;YACtD,WAAW,EAAE,IAAI;YACjB,OAAO,EAAE,GAAG,EAAE;gBACZ,MAAM,MAAM,GAAG,MAAM,EAAE,SAAS,EAAE,IAAI;oBACpC,SAAS,EAAE,KAAK;oBAChB,MAAM,EAAE,IAAI;oBACZ,eAAe,EAAE,CAAC;oBAClB,eAAe,EAAE,CAAC;iBACnB,CAAC;gBACF,OAAO;oBACL,IAAI,EAAE;wBACJ,sBAAsB;wBACtB,cAAc,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE;wBAC5C,WAAW,MAAM,CAAC,MAAM,IAAI,KAAK,EAAE;wBACnC,gBAAgB,MAAM,CAAC,eAAe,EAAE;wBACxC,qBAAqB,MAAM,CAAC,eAAe,EAAE;qBAC9C,CAAC,IAAI,CAAC,IAAI,CAAC;iBACb,CAAC;YACJ,CAAC;SACF,CAAC,CAAC;QAEH,kDAAkD;QAClD,GAAG,CAAC,qBAAqB,CAAC,mBAAmB,EAAE,KAAK,IAAI,EAAE;YACxD,OAAO,MAAM,EAAE,SAAS,EAAE,IAAI;gBAC5B,SAAS,EAAE,KAAK;gBAChB,MAAM,EAAE,IAAI;gBACZ,eAAe,EAAE,CAAC;gBAClB,eAAe,EAAE,CAAC;aACnB,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC;CACF,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/dist/src/config.d.ts

@@ -0,0 +1,19 @@
+export type NatsEventStoreConfig = {
+    enabled: boolean;
+    natsUrl: string;
+    streamName: string;
+    subjectPrefix: string;
+    retention: {
+        maxMessages: number;
+        maxBytes: number;
+        maxAgeHours: number;
+    };
+    publishTimeoutMs: number;
+    connectTimeoutMs: number;
+    drainTimeoutMs: number;
+    includeHooks: string[];
+    excludeHooks: string[];
+};
+export declare const DEFAULTS: NatsEventStoreConfig;
+export declare function resolveConfig(pluginConfig?: Record<string, unknown>): NatsEventStoreConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/src/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE;QACT,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB,CAAC;AAEF,eAAO,MAAM,QAAQ,EAAE,oBAetB,CAAC;AAEF,wBAAgB,aAAa,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,oBAAoB,CAmB1F"}

package/dist/src/config.js

@@ -0,0 +1,37 @@
+export const DEFAULTS = {
+    enabled: true,
+    natsUrl: "nats://localhost:4222",
+    streamName: "openclaw-events",
+    subjectPrefix: "openclaw.events",
+    retention: {
+        maxMessages: -1,
+        maxBytes: -1,
+        maxAgeHours: 0,
+    },
+    publishTimeoutMs: 5000,
+    connectTimeoutMs: 5000,
+    drainTimeoutMs: 5000,
+    includeHooks: [],
+    excludeHooks: [],
+};
+export function resolveConfig(pluginConfig) {
+    const raw = pluginConfig ?? {};
+    const retention = raw.retention;
+    return {
+        enabled: typeof raw.enabled === "boolean" ? raw.enabled : DEFAULTS.enabled,
+        natsUrl: typeof raw.natsUrl === "string" ? raw.natsUrl : DEFAULTS.natsUrl,
+        streamName: typeof raw.streamName === "string" ? raw.streamName : DEFAULTS.streamName,
+        subjectPrefix: typeof raw.subjectPrefix === "string" ? raw.subjectPrefix : DEFAULTS.subjectPrefix,
+        retention: {
+            maxMessages: retention?.maxMessages != null ? Number(retention.maxMessages) : DEFAULTS.retention.maxMessages,
+            maxBytes: retention?.maxBytes != null ? Number(retention.maxBytes) : DEFAULTS.retention.maxBytes,
+            maxAgeHours: retention?.maxAgeHours != null ? Number(retention.maxAgeHours) : DEFAULTS.retention.maxAgeHours,
+        },
+        publishTimeoutMs: typeof raw.publishTimeoutMs === "number" ? raw.publishTimeoutMs : DEFAULTS.publishTimeoutMs,
+        connectTimeoutMs: typeof raw.connectTimeoutMs === "number" ? raw.connectTimeoutMs : DEFAULTS.connectTimeoutMs,
+        drainTimeoutMs: typeof raw.drainTimeoutMs === "number" ? raw.drainTimeoutMs : DEFAULTS.drainTimeoutMs,
+        includeHooks: Array.isArray(raw.includeHooks) ? raw.includeHooks : DEFAULTS.includeHooks,
+        excludeHooks: Array.isArray(raw.excludeHooks) ? raw.excludeHooks : DEFAULTS.excludeHooks,
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/src/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAiBA,MAAM,CAAC,MAAM,QAAQ,GAAyB;IAC5C,OAAO,EAAE,IAAI;IACb,OAAO,EAAE,uBAAuB;IAChC,UAAU,EAAE,iBAAiB;IAC7B,aAAa,EAAE,iBAAiB;IAChC,SAAS,EAAE;QACT,WAAW,EAAE,CAAC,CAAC;QACf,QAAQ,EAAE,CAAC,CAAC;QACZ,WAAW,EAAE,CAAC;KACf;IACD,gBAAgB,EAAE,IAAI;IACtB,gBAAgB,EAAE,IAAI;IACtB,cAAc,EAAE,IAAI;IACpB,YAAY,EAAE,EAAE;IAChB,YAAY,EAAE,EAAE;CACjB,CAAC;AAEF,MAAM,UAAU,aAAa,CAAC,YAAsC;IAClE,MAAM,GAAG,GAAG,YAAY,IAAI,EAAE,CAAC;IAC/B,MAAM,SAAS,GAAG,GAAG,CAAC,SAAgD,CAAC;IACvE,OAAO;QACL,OAAO,EAAE,OAAO,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO;QAC1E,OAAO,EAAE,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO;QACzE,UAAU,EAAE,OAAO,GAAG,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,UAAU;QACrF,aAAa,EAAE,OAAO,GAAG,CAAC,aAAa,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,aAAa;QACjG,SAAS,EAAE;YACT,WAAW,EAAE,SAAS,EAAE,WAAW,IAAI,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,WAAW;YAC5G,QAAQ,EAAE,SAAS,EAAE,QAAQ,IAAI,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,QAAQ;YAChG,WAAW,EAAE,SAAS,EAAE,WAAW,IAAI,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,WAAW;SAC7G;QACD,gBAAgB,EAAE,OAAO,GAAG,CAAC,gBAAgB,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,CAAC,QAAQ,CAAC,gBAAgB;QAC7G,gBAAgB,EAAE,OAAO,GAAG,CAAC,gBAAgB,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,CAAC,QAAQ,CAAC,gBAAgB;QAC7G,cAAc,EAAE,OAAO,GAAG,CAAC,cAAc,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,QAAQ,CAAC,cAAc;QACrG,YAAY,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,QAAQ,CAAC,YAAY;QACxF,YAAY,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,QAAQ,CAAC,YAAY;KACzF,CAAC;AACJ,CAAC"}

package/dist/src/events.d.ts

@@ -0,0 +1,18 @@
+export type EventType = "msg.in" | "msg.out" | "msg.sending" | "tool.call" | "tool.result" | "run.start" | "run.end" | "run.error" | "llm.input" | "llm.output" | "session.start" | "session.end" | "session.compaction_start" | "session.compaction_end" | "session.reset" | "gateway.start" | "gateway.stop";
+export type ClawEvent = {
+    /** Unique event ID (UUIDv4) */
+    id: string;
+    /** Unix timestamp in milliseconds */
+    ts: number;
+    /** Agent ID (e.g., "main", "viola") */
+    agent: string;
+    /** Session key (e.g., "main", "viola:telegram:12345") */
+    session: string;
+    /** Event type identifier */
+    type: EventType;
+    /** Event-specific payload */
+    payload: Record<string, unknown>;
+};
+/** All known event types as an array (useful for validation/testing) */
+export declare const ALL_EVENT_TYPES: EventType[];
+//# sourceMappingURL=events.d.ts.map

package/dist/src/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/events.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GAEjB,QAAQ,GACR,SAAS,GACT,aAAa,GACb,WAAW,GACX,aAAa,GACb,WAAW,GACX,SAAS,GACT,WAAW,GAEX,WAAW,GACX,YAAY,GACZ,eAAe,GACf,aAAa,GACb,0BAA0B,GAC1B,wBAAwB,GACxB,eAAe,GACf,eAAe,GACf,cAAc,CAAC;AAEnB,MAAM,MAAM,SAAS,GAAG;IACtB,+BAA+B;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,qCAAqC;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,IAAI,EAAE,SAAS,CAAC;IAChB,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC,CAAC;AAEF,wEAAwE;AACxE,eAAO,MAAM,eAAe,EAAE,SAAS,EAkBtC,CAAC"}

package/dist/src/events.js

@@ -0,0 +1,21 @@
+/** All known event types as an array (useful for validation/testing) */
+export const ALL_EVENT_TYPES = [
+    "msg.in",
+    "msg.out",
+    "msg.sending",
+    "tool.call",
+    "tool.result",
+    "run.start",
+    "run.end",
+    "run.error",
+    "llm.input",
+    "llm.output",
+    "session.start",
+    "session.end",
+    "session.compaction_start",
+    "session.compaction_end",
+    "session.reset",
+    "gateway.start",
+    "gateway.stop",
+];
+//# sourceMappingURL=events.js.map

package/dist/src/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/events.ts"],"names":[],"mappings":"AAoCA,wEAAwE;AACxE,MAAM,CAAC,MAAM,eAAe,GAAgB;IAC1C,QAAQ;IACR,SAAS;IACT,aAAa;IACb,WAAW;IACX,aAAa;IACb,WAAW;IACX,SAAS;IACT,WAAW;IACX,WAAW;IACX,YAAY;IACZ,eAAe;IACf,aAAa;IACb,0BAA0B;IAC1B,wBAAwB;IACxB,eAAe;IACf,eAAe;IACf,cAAc;CACf,CAAC"}

package/dist/src/hooks.d.ts

@@ -0,0 +1,14 @@
+import type { NatsClient } from "./nats-client.js";
+import type { PluginLogger } from "./nats-client.js";
+import type { NatsEventStoreConfig } from "./config.js";
+type PluginApi = {
+    logger: PluginLogger;
+    on: (hookName: string, handler: (...args: any[]) => void) => void;
+};
+/**
+ * Register all event hook handlers on the plugin API.
+ * Uses a data-driven mapping table — each hook is registered via a single loop.
+ */
+export declare function registerEventHooks(api: PluginApi, config: NatsEventStoreConfig, getClient: () => NatsClient | null): void;
+export {};
+//# sourceMappingURL=hooks.d.ts.map

package/dist/src/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/hooks.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAYxD,KAAK,SAAS,GAAG;IACf,MAAM,EAAE,YAAY,CAAC;IACrB,EAAE,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,KAAK,IAAI,CAAC;CACnE,CAAC;AAoOF;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,SAAS,EACd,MAAM,EAAE,oBAAoB,EAC5B,SAAS,EAAE,MAAM,UAAU,GAAG,IAAI,GACjC,IAAI,CAiDN"}

package/dist/src/hooks.js

@@ -0,0 +1,239 @@
+import { randomUUID } from "node:crypto";
+import { extractAgentId, buildSubject } from "./util.js";
+/** Check if a hook should be published based on include/exclude config. */
+function shouldPublish(hookName, config) {
+    if (config.includeHooks.length > 0) {
+        return config.includeHooks.includes(hookName);
+    }
+    if (config.excludeHooks.length > 0) {
+        return !config.excludeHooks.includes(hookName);
+    }
+    return true;
+}
+/** Fire-and-forget publish of a ClawEvent to NATS. */
+function publish(getClient, config, type, agent, session, payload, logger) {
+    const client = getClient();
+    if (!client?.isConnected())
+        return;
+    const event = {
+        id: randomUUID(),
+        ts: Date.now(),
+        agent,
+        session,
+        type,
+        payload,
+    };
+    const subject = buildSubject(config.subjectPrefix, agent, type);
+    client.publish(subject, JSON.stringify(event)).catch((err) => {
+        logger.warn(`[nats-eventstore] Publish ${type} failed: ${err}`);
+    });
+}
+const HOOK_MAPPINGS = [
+    {
+        hookName: "message_received",
+        eventType: "msg.in",
+        mapper: (event, ctx) => ({
+            from: event.from,
+            content: event.content,
+            timestamp: event.timestamp,
+            channel: ctx?.channelId,
+            metadata: event.metadata,
+        }),
+    },
+    {
+        hookName: "message_sending",
+        eventType: "msg.sending",
+        mapper: (event, ctx) => ({
+            to: event.to,
+            content: event.content,
+            channel: ctx?.channelId,
+        }),
+    },
+    {
+        hookName: "message_sent",
+        eventType: "msg.out",
+        mapper: (event, ctx) => ({
+            to: event.to,
+            content: event.content,
+            success: event.success,
+            error: event.error,
+            channel: ctx?.channelId,
+        }),
+    },
+    {
+        hookName: "before_tool_call",
+        eventType: "tool.call",
+        mapper: (event) => ({
+            toolName: event.toolName,
+            params: event.params,
+        }),
+    },
+    {
+        hookName: "after_tool_call",
+        eventType: "tool.result",
+        mapper: (event) => ({
+            toolName: event.toolName,
+            params: event.params,
+            result: event.result,
+            error: event.error,
+            durationMs: event.durationMs,
+        }),
+    },
+    {
+        hookName: "before_agent_start",
+        eventType: "run.start",
+        mapper: (event) => ({ prompt: event.prompt }),
+    },
+    {
+        hookName: "agent_end",
+        eventType: "run.end",
+        mapper: (event) => ({
+            success: event.success,
+            error: event.error,
+            durationMs: event.durationMs,
+            messageCount: event.messages?.length ?? 0,
+        }),
+    },
+    {
+        hookName: "llm_input",
+        eventType: "llm.input",
+        mapper: (event) => ({
+            runId: event.runId,
+            sessionId: event.sessionId,
+            provider: event.provider,
+            model: event.model,
+            systemPromptLength: event.systemPrompt?.length ?? 0,
+            promptLength: event.prompt?.length ?? 0,
+            historyMessageCount: event.historyMessages?.length ?? 0,
+            imagesCount: event.imagesCount ?? 0,
+        }),
+    },
+    {
+        hookName: "llm_output",
+        eventType: "llm.output",
+        mapper: (event) => {
+            const texts = event.assistantTexts ?? [];
+            return {
+                runId: event.runId,
+                sessionId: event.sessionId,
+                provider: event.provider,
+                model: event.model,
+                assistantTextCount: texts.length,
+                assistantTextTotalLength: texts.reduce((s, t) => s + (t?.length ?? 0), 0),
+                usage: event.usage,
+            };
+        },
+    },
+    {
+        hookName: "before_compaction",
+        eventType: "session.compaction_start",
+        mapper: (event) => ({
+            messageCount: event.messageCount,
+            compactingCount: event.compactingCount,
+            tokenCount: event.tokenCount,
+        }),
+    },
+    {
+        hookName: "after_compaction",
+        eventType: "session.compaction_end",
+        mapper: (event) => ({
+            messageCount: event.messageCount,
+            compactedCount: event.compactedCount,
+            tokenCount: event.tokenCount,
+        }),
+    },
+    {
+        hookName: "before_reset",
+        eventType: "session.reset",
+        mapper: (event) => ({ reason: event.reason }),
+    },
+    {
+        hookName: "session_start",
+        eventType: "session.start",
+        mapper: (event) => ({
+            sessionId: event.sessionId,
+            resumedFrom: event.resumedFrom,
+        }),
+    },
+    {
+        hookName: "session_end",
+        eventType: "session.end",
+        mapper: (event) => ({
+            sessionId: event.sessionId,
+            messageCount: event.messageCount,
+            durationMs: event.durationMs,
+        }),
+    },
+    {
+        hookName: "gateway_start",
+        eventType: "gateway.start",
+        mapper: (event) => ({ port: event.port }),
+        systemEvent: true,
+    },
+    {
+        hookName: "gateway_stop",
+        eventType: "gateway.stop",
+        mapper: (event) => ({ reason: event.reason }),
+        systemEvent: true,
+    },
+];
+/** Extra events emitted from existing hooks (backward compatibility). */
+const EXTRA_EMITTERS = [
+    {
+        hookName: "agent_end",
+        eventType: "run.error",
+        condition: (event) => !event.success,
+        mapper: (event) => ({
+            success: false,
+            error: event.error,
+            durationMs: event.durationMs,
+        }),
+    },
+];
+/**
+ * Register all event hook handlers on the plugin API.
+ * Uses a data-driven mapping table — each hook is registered via a single loop.
+ */
+export function registerEventHooks(api, config, getClient) {
+    const logger = api.logger;
+    // Helper: publish with agent context extraction
+    const pub = (type, ctx, payload) => {
+        const agent = extractAgentId(ctx);
+        const session = ctx.sessionKey ?? ctx.sessionId ?? "unknown";
+        publish(getClient, config, type, agent, session, payload, logger);
+    };
+    // Build lookup for extra emitters per hook
+    const extrasByHook = new Map();
+    for (const extra of EXTRA_EMITTERS) {
+        const list = extrasByHook.get(extra.hookName) ?? [];
+        list.push(extra);
+        extrasByHook.set(extra.hookName, list);
+    }
+    // Register each hook from the mapping table
+    for (const mapping of HOOK_MAPPINGS) {
+        if (!shouldPublish(mapping.hookName, config))
+            continue;
+        const extras = extrasByHook.get(mapping.hookName) ?? [];
+        api.on(mapping.hookName, (event, ctx) => {
+            try {
+                const payload = mapping.mapper(event, ctx);
+                if (mapping.systemEvent) {
+                    publish(getClient, config, mapping.eventType, "system", "system", payload, logger);
+                }
+                else {
+                    pub(mapping.eventType, ctx, payload);
+                }
+                // Emit any extra events for this hook
+                for (const extra of extras) {
+                    if (extra.condition(event)) {
+                        pub(extra.eventType, ctx, extra.mapper(event, ctx));
+                    }
+                }
+            }
+            catch (err) {
+                logger.warn(`[nats-eventstore] Hook ${mapping.hookName} error: ${err}`);
+            }
+        });
+    }
+}
+//# sourceMappingURL=hooks.js.map

package/dist/src/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../src/hooks.ts"],"names":[],"mappings":"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"}

package/dist/src/nats-client.d.ts

@@ -0,0 +1,33 @@
+import type { NatsEventStoreConfig } from "./config.js";
+export type PluginLogger = {
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+    debug: (msg: string) => void;
+};
+export type NatsClient = {
+    publish(subject: string, data: string): Promise<void>;
+    isConnected(): boolean;
+    getStatus(): NatsClientStatus;
+    drain(): Promise<void>;
+    close(): Promise<void>;
+};
+export type NatsClientStatus = {
+    connected: boolean;
+    stream: string | null;
+    disconnectCount: number;
+    publishFailures: number;
+};
+/**
+ * Parse a NATS URL, extracting user/pass and returning a safe URL for logging.
+ *
+ * Example: "nats://user:pass@host:4222" → { servers: "host:4222", user: "user", pass: "pass", safeUrl: "nats://host:4222" }
+ */
+export declare function parseNatsUrl(url: string): {
+    servers: string;
+    user?: string;
+    pass?: string;
+    safeUrl: string;
+};
+export declare function createNatsClient(config: NatsEventStoreConfig, logger: PluginLogger): Promise<NatsClient>;
+//# sourceMappingURL=nats-client.d.ts.map

package/dist/src/nats-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nats-client.d.ts","sourceRoot":"","sources":["../../src/nats-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAExD,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,WAAW,IAAI,OAAO,CAAC;IACvB,SAAS,IAAI,gBAAgB,CAAC;IAC9B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;CACzB,CAAC;AAIF;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB,CAcA;AAmED,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,oBAAoB,EAC5B,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,UAAU,CAAC,CAqFrB"}

package/dist/src/nats-client.js

@@ -0,0 +1,151 @@
+const MAX_PUBLISH_FAILURES_BEFORE_WARN = 10;
+/**
+ * Parse a NATS URL, extracting user/pass and returning a safe URL for logging.
+ *
+ * Example: "nats://user:pass@host:4222" → { servers: "host:4222", user: "user", pass: "pass", safeUrl: "nats://host:4222" }
+ */
+export function parseNatsUrl(url) {
+    try {
+        const parsed = new URL(url);
+        const user = parsed.username || undefined;
+        const pass = parsed.password || undefined;
+        const host = parsed.hostname;
+        const port = parsed.port || "4222";
+        const servers = `${host}:${port}`;
+        const safeUrl = `${parsed.protocol}//${host}:${port}`;
+        return { servers, user, pass, safeUrl };
+    }
+    catch {
+        // If URL parsing fails, return as-is
+        return { servers: url, safeUrl: url };
+    }
+}
+async function ensureStream(nc, config, logger) {
+    const jsm = await nc.jetstreamManager();
+    try {
+        await jsm.streams.info(config.streamName);
+        logger.debug(`[nats-eventstore] Stream "${config.streamName}" exists`);
+    }
+    catch (err) {
+        // Stream doesn't exist — create it
+        // nats.js v2+: JetStream API errors use err.api_error?.code (numeric)
+        const apiCode = err?.api_error?.code;
+        const errCode = err?.code;
+        const isNotFound = apiCode === 404 ||
+            errCode === 404 ||
+            errCode === "404" ||
+            err?.message?.includes("not found") ||
+            err?.message?.includes("stream not found");
+        if (isNotFound) {
+            const streamConfig = {
+                name: config.streamName,
+                subjects: [`${config.subjectPrefix}.>`],
+                retention: "limits",
+                max_msgs: config.retention.maxMessages,
+                max_bytes: config.retention.maxBytes,
+                max_age: config.retention.maxAgeHours > 0
+                    ? config.retention.maxAgeHours * 60 * 60 * 1_000_000_000 // nanoseconds
+                    : 0,
+            };
+            await jsm.streams.add(streamConfig);
+            logger.info(`[nats-eventstore] Created stream "${config.streamName}"`);
+        }
+        else {
+            throw err;
+        }
+    }
+}
+function monitorConnection(nc, counters, logger) {
+    (async () => {
+        for await (const status of nc.status()) {
+            switch (status.type) {
+                case "disconnect":
+                    counters.disconnects++;
+                    logger.warn(`[nats-eventstore] Disconnected (${counters.disconnects} total)`);
+                    break;
+                case "reconnect":
+                    logger.info("[nats-eventstore] Reconnected");
+                    break;
+                case "error":
+                    logger.error(`[nats-eventstore] Connection error: ${status.data}`);
+                    break;
+            }
+        }
+    })().catch(() => {
+        // Iterator ends when connection closes — expected
+    });
+}
+export async function createNatsClient(config, logger) {
+    const nats = await import("nats");
+    const parsed = parseNatsUrl(config.natsUrl);
+    const nc = await nats.connect({
+        servers: parsed.servers,
+        user: parsed.user,
+        pass: parsed.pass,
+        reconnect: true,
+        maxReconnectAttempts: -1,
+        timeout: config.connectTimeoutMs,
+    });
+    logger.info(`[nats-eventstore] Connected to ${parsed.safeUrl}`);
+    const js = nc.jetstream();
+    const sc = nats.StringCodec();
+    // Ensure stream exists
+    await ensureStream(nc, config, logger);
+    // Monitor connection status
+    const counters = { disconnects: 0, publishFailures: 0 };
+    monitorConnection(nc, counters, logger);
+    return {
+        async publish(subject, data) {
+            try {
+                const publishPromise = js.publish(subject, sc.encode(data));
+                if (config.publishTimeoutMs > 0) {
+                    let timer;
+                    await Promise.race([
+                        publishPromise,
+                        new Promise((_resolve, reject) => {
+                            timer = setTimeout(() => reject(new Error(`Publish timeout after ${config.publishTimeoutMs}ms`)), config.publishTimeoutMs);
+                        }),
+                    ]).finally(() => clearTimeout(timer));
+                }
+                else {
+                    await publishPromise;
+                }
+                counters.publishFailures = 0;
+            }
+            catch (err) {
+                counters.publishFailures++;
+                if (counters.publishFailures === 1 ||
+                    counters.publishFailures % MAX_PUBLISH_FAILURES_BEFORE_WARN === 0) {
+                    logger.warn(`[nats-eventstore] Publish failed (${counters.publishFailures} consecutive): ${err}`);
+                }
+                // Non-fatal: do not throw. Agent operations must never be blocked by event store.
+            }
+        },
+        isConnected: () => !nc.isClosed(),
+        getStatus: () => ({
+            connected: !nc.isClosed(),
+            stream: config.streamName,
+            disconnectCount: counters.disconnects,
+            publishFailures: counters.publishFailures,
+        }),
+        async drain() {
+            let timer;
+            try {
+                await Promise.race([
+                    nc.drain(),
+                    new Promise((_resolve, reject) => {
+                        timer = setTimeout(() => reject(new Error("Drain timeout")), config.drainTimeoutMs);
+                    }),
+                ]).finally(() => clearTimeout(timer));
+            }
+            catch {
+                logger.warn("[nats-eventstore] Drain timed out, forcing close");
+                await nc.close().catch(() => { });
+            }
+        },
+        async close() {
+            await nc.close().catch(() => { });
+        },
+    };
+}
+//# sourceMappingURL=nats-client.js.map

package/dist/src/nats-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nats-client.js","sourceRoot":"","sources":["../../src/nats-client.ts"],"names":[],"mappings":"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"}

package/dist/src/service.d.ts

@@ -0,0 +1,18 @@
+import type { NatsClient, PluginLogger } from "./nats-client.js";
+export type ServiceContext = {
+    logger: PluginLogger;
+    config: {
+        plugins?: {
+            entries?: Record<string, {
+                config?: Record<string, unknown>;
+            }>;
+        };
+    };
+};
+export type PluginService = {
+    id: string;
+    start: (ctx: ServiceContext) => Promise<void>;
+    stop: (ctx: ServiceContext) => Promise<void>;
+};
+export declare function createEventStoreService(getClient: () => NatsClient | null, setClient: (client: NatsClient | null) => void): PluginService;
+//# sourceMappingURL=service.d.ts.map

package/dist/src/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAIjE,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE;QACN,OAAO,CAAC,EAAE;YACR,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;gBAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;aAAE,CAAC,CAAC;SAChE,CAAC;KACH,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,IAAI,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9C,CAAC;AAEF,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,UAAU,GAAG,IAAI,EAClC,SAAS,EAAE,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,KAAK,IAAI,GAC7C,aAAa,CA6Bf"}

package/dist/src/service.js

@@ -0,0 +1,33 @@
+import { createNatsClient } from "./nats-client.js";
+import { resolveConfig } from "./config.js";
+export function createEventStoreService(getClient, setClient) {
+    return {
+        id: "nats-eventstore",
+        async start(ctx) {
+            const pluginEntry = ctx.config.plugins?.entries?.["nats-eventstore"];
+            const config = resolveConfig(pluginEntry?.config);
+            if (!config.enabled) {
+                ctx.logger.info("[nats-eventstore] Disabled");
+                return;
+            }
+            try {
+                const client = await createNatsClient(config, ctx.logger);
+                setClient(client);
+                ctx.logger.info("[nats-eventstore] Ready");
+            }
+            catch (err) {
+                ctx.logger.error(`[nats-eventstore] Init failed: ${err}`);
+                // Non-fatal: gateway continues without event store
+            }
+        },
+        async stop(ctx) {
+            const client = getClient();
+            if (!client)
+                return;
+            await client.drain();
+            setClient(null);
+            ctx.logger.info("[nats-eventstore] Shutdown");
+        },
+    };
+}
+//# sourceMappingURL=service.js.map

package/dist/src/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../../src/service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAiB5C,MAAM,UAAU,uBAAuB,CACrC,SAAkC,EAClC,SAA8C;IAE9C,OAAO;QACL,EAAE,EAAE,iBAAiB;QACrB,KAAK,CAAC,KAAK,CAAC,GAAG;YACb,MAAM,WAAW,GAAG,GAAG,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,CAAC,iBAAiB,CAAC,CAAC;YACrE,MAAM,MAAM,GAAG,aAAa,CAAC,WAAW,EAAE,MAAiC,CAAC,CAAC;YAE7E,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBACpB,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,4BAA4B,CAAC,CAAC;gBAC9C,OAAO;YACT,CAAC;YAED,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;gBAC1D,SAAS,CAAC,MAAM,CAAC,CAAC;gBAClB,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC;YAC7C,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,kCAAkC,GAAG,EAAE,CAAC,CAAC;gBAC1D,mDAAmD;YACrD,CAAC;QACH,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,GAAG;YACZ,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;YAC3B,IAAI,CAAC,MAAM;gBAAE,OAAO;YACpB,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;YACrB,SAAS,CAAC,IAAI,CAAC,CAAC;YAChB,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,4BAA4B,CAAC,CAAC;QAChD,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/src/util.d.ts

@@ -0,0 +1,17 @@
+import type { EventType } from "./events.js";
+/**
+ * Extract agent ID from context.
+ * Priority: ctx.agentId → ctx.sessionKey first segment → "main"
+ */
+export declare function extractAgentId(ctx: {
+    agentId?: string;
+    sessionKey?: string;
+}): string;
+/**
+ * Build a NATS subject from prefix, agent ID, and event type.
+ * Dots in the event type are replaced with underscores for NATS subject compatibility.
+ *
+ * Example: buildSubject("openclaw.events", "main", "msg.in") → "openclaw.events.main.msg_in"
+ */
+export declare function buildSubject(prefix: string, agent: string, eventType: EventType): string;
+//# sourceMappingURL=util.d.ts.map

package/dist/src/util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.d.ts","sourceRoot":"","sources":["../../src/util.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAOrF;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,GAAG,MAAM,CAExF"}

package/dist/src/util.js

@@ -0,0 +1,24 @@
+/**
+ * Extract agent ID from context.
+ * Priority: ctx.agentId → ctx.sessionKey first segment → "main"
+ */
+export function extractAgentId(ctx) {
+    if (ctx.agentId && ctx.agentId !== "main")
+        return ctx.agentId;
+    if (ctx.sessionKey) {
+        if (ctx.sessionKey === "main")
+            return "main";
+        return ctx.sessionKey.split(":")[0] ?? "main";
+    }
+    return "main";
+}
+/**
+ * Build a NATS subject from prefix, agent ID, and event type.
+ * Dots in the event type are replaced with underscores for NATS subject compatibility.
+ *
+ * Example: buildSubject("openclaw.events", "main", "msg.in") → "openclaw.events.main.msg_in"
+ */
+export function buildSubject(prefix, agent, eventType) {
+    return `${prefix}.${agent}.${eventType.replace(/\./g, "_")}`;
+}
+//# sourceMappingURL=util.js.map

package/dist/src/util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.js","sourceRoot":"","sources":["../../src/util.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,GAA8C;IAC3E,IAAI,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,OAAO,KAAK,MAAM;QAAE,OAAO,GAAG,CAAC,OAAO,CAAC;IAC9D,IAAI,GAAG,CAAC,UAAU,EAAE,CAAC;QACnB,IAAI,GAAG,CAAC,UAAU,KAAK,MAAM;YAAE,OAAO,MAAM,CAAC;QAC7C,OAAO,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC;IAChD,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc,EAAE,KAAa,EAAE,SAAoB;IAC9E,OAAO,GAAG,MAAM,IAAI,KAAK,IAAI,SAAS,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,CAAC;AAC/D,CAAC"}

package/openclaw.plugin.json

@@ -0,0 +1,81 @@
+{
+  "id": "nats-eventstore",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "enabled": {
+        "type": "boolean",
+        "default": true,
+        "description": "Enable/disable event publishing"
+      },
+      "natsUrl": {
+        "type": "string",
+        "default": "nats://localhost:4222",
+        "description": "NATS server URL. Supports auth: nats://user:pass@host:port"
+      },
+      "streamName": {
+        "type": "string",
+        "default": "openclaw-events",
+        "description": "JetStream stream name"
+      },
+      "subjectPrefix": {
+        "type": "string",
+        "default": "openclaw.events",
+        "description": "Subject prefix for all published events"
+      },
+      "retention": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "maxMessages": {
+            "type": "integer",
+            "minimum": -1,
+            "default": -1,
+            "description": "Maximum messages to retain (-1 = unlimited)"
+          },
+          "maxBytes": {
+            "type": "integer",
+            "minimum": -1,
+            "default": -1,
+            "description": "Maximum bytes to retain (-1 = unlimited)"
+          },
+          "maxAgeHours": {
+            "type": "number",
+            "minimum": 0,
+            "default": 0,
+            "description": "Maximum age of messages in hours (0 = unlimited)"
+          }
+        }
+      },
+      "publishTimeoutMs": {
+        "type": "integer",
+        "minimum": 100,
+        "default": 5000,
+        "description": "Timeout for individual publish operations"
+      },
+      "connectTimeoutMs": {
+        "type": "integer",
+        "minimum": 1000,
+        "default": 5000,
+        "description": "Timeout for initial NATS connection"
+      },
+      "drainTimeoutMs": {
+        "type": "integer",
+        "minimum": 1000,
+        "default": 5000,
+        "description": "Timeout for graceful drain on shutdown"
+      },
+      "includeHooks": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "Whitelist of hook names to publish (empty = all)"
+      },
+      "excludeHooks": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "Blacklist of hook names to skip"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@vainplex/nats-eventstore",
+  "version": "0.2.0",
+  "description": "OpenClaw plugin: publish agent events to NATS JetStream for audit, replay, and multi-agent sharing",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "openclaw.plugin.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "nats": "^2.29.0"
+  },
+  "devDependencies": {
+    "vitest": "^3.0.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ]
+  },
+  "peerDependencies": {},
+  "keywords": [
+    "openclaw",
+    "plugin",
+    "nats",
+    "jetstream",
+    "event-store",
+    "audit"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alberthild/openclaw-nats-eventstore.git"
+  },
+  "homepage": "https://github.com/alberthild/openclaw-nats-eventstore#readme",
+  "bugs": {
+    "url": "https://github.com/alberthild/openclaw-nats-eventstore/issues"
+  },
+  "author": "Vainplex <hildalbert@gmail.com>"
+}