@ekai/contexto 0.1.0 → 0.1.1-rc.0

package/README.md

@@ -0,0 +1,107 @@
+# @ekai/contexto
+
+OpenClaw plugin that captures all 13 lifecycle events to structured JSONL storage. Built for context, memory, and analytics.
+
+Uses [`@ekai/store`](../../store/) for event normalization, safe serialization, and per-session file organization.
+
+## Install
+
+```bash
+openclaw plugins install @ekai/contexto
+```
+
+## Configure
+
+In your OpenClaw config:
+
+```json5
+{
+  plugins: {
+    allow: ["ekai-contexto"],
+    entries: {
+      "ekai-contexto": {
+        enabled: true,
+        config: { "dataDir": "~/.openclaw/ekai/data" }
+      }
+    }
+  }
+}
+```
+
+`dataDir` defaults to `~/.openclaw/ekai/data` if not set.
+
+## Verify
+
+```bash
+openclaw plugins list       # should show ekai-contexto
+openclaw hooks list          # should show plugin:ekai-contexto:contexto:* hooks
+```
+
+## Storage Layout
+
+Events are organized as one JSONL file per session, grouped by agent:
+
+```
+{dataDir}/
+  {agent_id}/
+    {session_id}.jsonl
+```
+
+IDs are sanitized for safe file paths (`[a-zA-Z0-9_-]` + 8-char SHA-256 hash suffix). Missing IDs fall back to `_unknown-agent` / `_unknown-session`.
+
+Each line is a JSON object with a versioned schema:
+
+```json
+{"id":"...","v":1,"eventTs":1709500000000,"ingestTs":1709500000050,"hook":"llm_output","sessionId":"abc-3f2a1b9c","agentId":"default-8e4c7d1a","event":{...},"ctx":{...}}
+```
+
+## What It Captures
+
+All 13 OpenClaw lifecycle hooks:
+
+| Hook | Description |
+|------|-------------|
+| `session_start` | Session opened |
+| `session_end` | Session closed |
+| `message_received` | Inbound message |
+| `message_sent` | Outbound message |
+| `before_prompt_build` | Pre-prompt state |
+| `llm_input` | LLM request |
+| `llm_output` | LLM response |
+| `before_tool_call` | Pre-tool invocation |
+| `after_tool_call` | Tool result |
+| `tool_result_persist` | Tool result persistence |
+| `agent_end` | Agent completion |
+| `before_compaction` | Pre-compaction state |
+| `after_compaction` | Post-compaction state |
+
+Additional fields extracted per event: `sessionId`, `agentId`, `userId`, `conversationId`.
+
+## Design
+
+- **Structured storage** — one JSONL file per session via `@ekai/store` EventWriter
+- **Safe serialization** — handles circular refs, BigInt, Error objects (never throws)
+- **Never crashes OpenClaw** — every handler wrapped in try/catch
+- **Sync writes** — `appendFileSync` for `tool_result_persist` compatibility
+- **ID sanitization** — safe file paths with collision-resistant hashing
+- **Schema versioned** — every event carries `v: 1` for future migration
+
+## Development
+
+```bash
+# Type-check (no build needed — OpenClaw loads .ts via jiti)
+npm run type-check --workspace=@ekai/contexto
+
+# Build the store dependency
+npm run build --workspace=store
+
+# Run store tests
+npm run test --workspace=store
+
+# Local dev install (symlink)
+openclaw plugins install -l ./integrations/openclaw
+```
+
+## License
+
+MIT

package/openclaw.plugin.json

@@ -4,13 +4,13 @@
     "type": "object",
     "additionalProperties": false,
     "properties": {
-      "logPath": { "type": "string" }
+      "dataDir": { "type": "string" }
     }
   },
   "uiHints": {
-    "logPath": {
-      "label": "Event log path",
-      "description": "Path to the JSONL event log file"
+    "dataDir": {
+      "label": "Event data directory",
+      "description": "Directory for structured JSONL event storage (one file per session)"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekai/contexto",
-  "version": "0.1.0",
+  "version": "0.1.1-rc.0",
   "description": "OpenClaw plugin — captures all lifecycle events to JSONL for context, memory, and analytics",
   "type": "module",
   "license": "MIT",
@@ -27,6 +27,9 @@
   "scripts": {
     "type-check": "tsc --noEmit"
   },
+  "dependencies": {
+    "@ekai/store": "*"
+  },
   "devDependencies": {
     "typescript": "^5.3.2"
   },

package/src/index.ts

@@ -1,47 +1,108 @@
-import { EventLog } from './store.js';
+import { EventWriter } from '@ekai/store';
 
-const HOOKS = [
+/** Hooks that store events (10 of 13). */
+const STORE_HOOKS = [
   { name: 'session_start', description: 'Log session start' },
   { name: 'session_end', description: 'Log session end' },
   { name: 'message_received', description: 'Log inbound message' },
   { name: 'message_sent', description: 'Log outbound message' },
-  { name: 'before_prompt_build', description: 'Log pre-prompt state' },
   { name: 'llm_input', description: 'Log LLM request' },
   { name: 'llm_output', description: 'Log LLM response' },
   { name: 'before_tool_call', description: 'Log pre-tool invocation' },
   { name: 'after_tool_call', description: 'Log tool result' },
   { name: 'tool_result_persist', description: 'Log tool result persistence' },
   { name: 'agent_end', description: 'Log agent completion' },
-  { name: 'before_compaction', description: 'Log pre-compaction state' },
-  { name: 'after_compaction', description: 'Log post-compaction state' },
+] as const;
+
+/** Hooks registered as no-ops — keeps OpenClaw aware we're listening. */
+const NOOP_HOOKS = [
+  { name: 'before_prompt_build', description: 'Stub for future memory injection' },
+  { name: 'before_compaction', description: 'Monitor compaction start' },
+  { name: 'after_compaction', description: 'Monitor compaction end' },
 ] as const;
 
 export default {
   id: 'ekai-contexto',
   name: 'Ekai Contexto',
   description: 'Context engine for OpenClaw — captures lifecycle events, extensible to memory injection',
-  configSchema: {},
+  configSchema: {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+      dataDir: { type: 'string' },
+    },
+  },
 
   register(api: any) {
-    const logPath = api.resolvePath(api.pluginConfig?.logPath ?? '~/.openclaw/ekai/events.jsonl');
-    const log = new EventLog(logPath);
+    const dataDir = api.resolvePath(api.pluginConfig?.dataDir ?? '~/.openclaw/ekai/data');
+    const store = new EventWriter(dataDir);
+
+    // Store hooks — fire-and-forget with .catch() logging
+    for (const hook of STORE_HOOKS) {
+      if (hook.name === 'agent_end') {
+        // agent_end: store event then flush for clean shutdown
+        api.registerHook({
+          name: `contexto:${hook.name}`,
+          description: hook.description,
+          hook: hook.name,
+          handler: (event: any, ctx: any) => {
+            const sessionId = event?.sessionId ?? ctx?.sessionId ?? ctx?.sessionKey;
+            const agentId = event?.agentId ?? ctx?.agentId;
+            const userId = event?.userId ?? ctx?.userId ?? ctx?.user;
+            const conversationId = event?.conversationId ?? ctx?.conversationId;
+
+            store.append({
+              hook: hook.name,
+              sessionId,
+              agentId,
+              userId,
+              conversationId,
+              event: event ?? {},
+              ctx,
+            })
+              .catch(err => api.logger.warn(`ekai-contexto: append failed: ${String(err)}`))
+              .finally(() => store.flush()
+                .catch(err => api.logger.warn(`ekai-contexto: flush failed: ${String(err)}`)));
+          },
+        });
+        continue;
+      }
 
-    for (const hook of HOOKS) {
       api.registerHook({
         name: `contexto:${hook.name}`,
         description: hook.description,
         hook: hook.name,
-        handler: (event: unknown, ctx: unknown) => {
-          try {
-            log.append(hook.name, event, ctx);
-          } catch (err) {
-            // Never crash OpenClaw — log the failure and move on
-            api.logger.warn(`ekai-contexto: failed to log ${hook.name}: ${String(err)}`);
-          }
+        handler: (event: any, ctx: any) => {
+          const sessionId = event?.sessionId ?? ctx?.sessionId ?? ctx?.sessionKey;
+          const agentId = event?.agentId ?? ctx?.agentId;
+          const userId = event?.userId ?? ctx?.userId ?? ctx?.user;
+          const conversationId = event?.conversationId ?? ctx?.conversationId;
+
+          store.append({
+            hook: hook.name,
+            sessionId,
+            agentId,
+            userId,
+            conversationId,
+            event: event ?? {},
+            ctx,
+          }).catch(err => {
+            api.logger.warn(`ekai-contexto: store.append failed: ${String(err)}`);
+          });
         },
       });
     }
 
-    api.logger.info(`ekai-contexto: logging to ${logPath}`);
+    // No-op hooks — registered so OpenClaw knows we're listening
+    for (const hook of NOOP_HOOKS) {
+      api.registerHook({
+        name: `contexto:${hook.name}`,
+        description: hook.description,
+        hook: hook.name,
+        handler: () => {},
+      });
+    }
+
+    api.logger.info(`ekai-contexto: storing events to ${dataDir}`);
   },
 };

package/src/store.ts

@@ -1,56 +0,0 @@
-import { appendFileSync, mkdirSync } from 'node:fs';
-import { dirname } from 'node:path';
-
-/**
- * Safe JSON replacer — handles circular refs, BigInt, undefined, errors.
- * No external deps needed.
- */
-function safeReplacer() {
-  const seen = new WeakSet();
-  return (_key: string, value: unknown): unknown => {
-    if (typeof value === 'bigint') return value.toString();
-    if (value instanceof Error) return { message: value.message, stack: value.stack };
-    if (value !== null && typeof value === 'object') {
-      if (seen.has(value)) return '[Circular]';
-      seen.add(value);
-    }
-    return value;
-  };
-}
-
-function safeStringify(obj: unknown): string {
-  try {
-    return JSON.stringify(obj, safeReplacer());
-  } catch {
-    return JSON.stringify({ _error: 'serialization failed' });
-  }
-}
-
-/**
- * Extract sessionId and agentId from event or ctx (whichever has them).
- */
-function extractIds(event: any, ctx: any): { sessionId?: string; agentId?: string } {
-  return {
-    sessionId: event?.sessionId ?? ctx?.sessionId ?? ctx?.sessionKey ?? undefined,
-    agentId: event?.agentId ?? ctx?.agentId ?? undefined,
-  };
-}
-
-export class EventLog {
-  constructor(private path: string) {
-    mkdirSync(dirname(path), { recursive: true });
-  }
-
-  /**
-   * Append a hook event to the JSONL log.
-   * Uses appendFileSync for tool_result_persist sync compatibility.
-   *
-   * NOTE (v0): appendFileSync blocks the event loop. Acceptable at low volume.
-   * Future: async write with buffering for high-throughput hooks.
-   */
-  append(hook: string, event: unknown, ctx: unknown): void {
-    const { sessionId, agentId } = extractIds(event, ctx);
-    const line = safeStringify({ ts: Date.now(), hook, sessionId, agentId, event, ctx });
-    appendFileSync(this.path, line + '\n');
-  }
-}