@ekai/contexto 0.1.1-rc.0 → 0.1.2

package/README.md

@@ -1,107 +1,75 @@
-# @ekai/contexto
+# @ekai/contexto (v1)
 
-OpenClaw plugin that captures all 13 lifecycle events to structured JSONL storage. Built for context, memory, and analytics.
+OpenClaw plugin — Context graph engine that prevents context rot by visualizing and organizing conversation context.
 
-Uses [`@ekai/store`](../../store/) for event normalization, safe serialization, and per-session file organization.
+## Purpose
 
-## Install
+Mind Map is an improved **context engine** for OpenClaw that solves **context rot** — the gradual degradation of agent responses as conversation history grows. It builds a contextual representation of your conversations that allows the agent to maintain relevance and coherence over extended sessions.
 
-```bash
-openclaw plugins install @ekai/contexto
-```
-
-## Configure
+- Uses **semantic clustering** to group related messages and concepts
+- Maps relationships between messages, concepts, and session states
+- Provides structured context retrieval to combat context rot
+- Enables the agent to understand conversation topology
 
-In your OpenClaw config:
+## Installation
 
-```json5
-{
-  plugins: {
-    allow: ["ekai-contexto"],
-    entries: {
-      "ekai-contexto": {
-        enabled: true,
-        config: { "dataDir": "~/.openclaw/ekai/data" }
-      }
-    }
-  }
-}
+```bash
+npm install @ekai/contexto
 ```
 
-`dataDir` defaults to `~/.openclaw/ekai/data` if not set.
+## OpenClaw Setup
 
-## Verify
+### 1. Install the plugin in OpenClaw
 
 ```bash
-openclaw plugins list       # should show ekai-contexto
-openclaw hooks list          # should show plugin:ekai-contexto:contexto:* hooks
+openclaw plugins install @ekai/contexto
 ```
 
-## Storage Layout
+### 2. Enable and configure the plugin
 
-Events are organized as one JSONL file per session, grouped by agent:
+Set your API key via CLI:
 
+```bash
+openclaw plugins config @ekai/contexto apiKey your-api-key-here
 ```
-{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:
+Or add to your OpenClaw config:
 
 ```json
-{"id":"...","v":1,"eventTs":1709500000000,"ingestTs":1709500000050,"hook":"llm_output","sessionId":"abc-3f2a1b9c","agentId":"default-8e4c7d1a","event":{...},"ctx":{...}}
+{
+  "plugins": {
+    "slots": {
+      "contextEngine": "@ekai/contexto"
+    },
+    "allow": ["@ekai/contexto"],
+    "entries": {
+      "@ekai/contexto": {
+        "enabled": true,
+        "config": {
+          "apiKey": "your-api-key-here"
+        }
+      }
+    }
+  }
+}
 ```
 
-## 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
+### 3. Restart OpenClaw
 
 ```bash
-# Type-check (no build needed — OpenClaw loads .ts via jiti)
-npm run type-check --workspace=@ekai/contexto
+openclaw gateway restart
+```
 
-# Build the store dependency
-npm run build --workspace=store
+## Configuration
 
-# Run store tests
-npm run test --workspace=store
+| Property | Type | Required | Description |
+| --- | --- | --- | --- |
+| `apiKey` | string | Yes | Your Contexto API key |
 
-# Local dev install (symlink)
-openclaw plugins install -l ./integrations/openclaw
-```
+## Version
+
+This is **v1** of @ekai/contexto. For the legacy version (v0), see [`../v0`](../v0).
 
 ## License
 
-MIT
+MIT

package/openclaw.plugin.json

@@ -1,16 +1,12 @@
 {
-  "id": "ekai-contexto",
+  "id": "@ekai/mindmap",
   "configSchema": {
     "type": "object",
-    "additionalProperties": false,
     "properties": {
-      "dataDir": { "type": "string" }
-    }
-  },
-  "uiHints": {
-    "dataDir": {
-      "label": "Event data directory",
-      "description": "Directory for structured JSONL event storage (one file per session)"
+      "apiKey": {
+        "type": "string",
+        "description": "API key for Bearer authentication"
+      }
     }
   }
-}
+}

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@ekai/contexto",
-  "version": "0.1.1-rc.0",
-  "description": "OpenClaw plugin — captures all lifecycle events to JSONL for context, memory, and analytics",
+  "version": "0.1.2",
+  "description": "OpenClaw plugin — sends all events to a webhook API",
   "type": "module",
   "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
   "main": "src/index.ts",
   "files": [
     "src/",
@@ -12,28 +15,23 @@
   "keywords": [
     "openclaw",
     "openclaw-plugin",
-    "ai",
-    "context",
-    "memory",
-    "lifecycle",
+    "webhook",
     "events"
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/ekai-labs/ekai-gateway",
-    "directory": "integrations/openclaw"
+    "url": "https://github.com/ekailabs/contexto",
+    "directory": "packages/contexto/v1"
   },
   "author": "Ekai Labs",
   "scripts": {
     "type-check": "tsc --noEmit"
   },
-  "dependencies": {
-    "@ekai/store": "*"
-  },
   "devDependencies": {
+    "@types/node": "^20.10.0",
     "typescript": "^5.3.2"
   },
   "openclaw": {
     "extensions": ["./src/index.ts"]
   }
-}
+}

package/src/index.ts

@@ -1,108 +1,187 @@
-import { EventWriter } from '@ekai/store';
-
-/** 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: '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' },
-] 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',
+const WEBHOOK_URL_BASE = 'https://api.getcontexto.com';
+
+interface WebhookConfig {
+  apiKey: string;
+  contextEnabled: boolean;
+}
+
+interface WebhookPayload {
+  event: {
+    type: string;
+    action: string;
+  };
+  sessionKey: string;
+  timestamp: string;
+  context: Record<string, unknown>;
+  agent?: Record<string, unknown>;
+  data?: Record<string, unknown>;
+}
+
+async function sendWebhook(config: WebhookConfig, payload: WebhookPayload, logger: any): Promise<void> {
+  try {
+    const response = await fetch(`${WEBHOOK_URL_BASE}/v1/webhooks/events`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${config.apiKey}`,
+      },
+      body: JSON.stringify(payload),
+    });
+
+    if (!response.ok) {
+      const body = await response.text().catch(() => '(no body)');
+      logger.warn(`[webhook] HTTP ${response.status}: ${response.statusText} — body: ${body}`);
+    } else {
+      logger.info(`[webhook] OK ${response.status} for ${payload.event.type}:${payload.event.action}`);
+    }
+  } catch (err) {
+    logger.warn(`[webhook] Failed to send: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+function buildPayload(
+  type: string,
+  action: string,
+  sessionKey: string,
+  context: Record<string, unknown>,
+  agent?: Record<string, unknown>,
+  data?: Record<string, unknown>
+): WebhookPayload {
+  return {
+    event: { type, action },
+    sessionKey,
+    timestamp: new Date().toISOString(),
+    context,
+    agent,
+    data,
+  };
+}
+
+const webhookPlugin = {
+  id: '@ekai/mindmap',
+  name: 'Mind Map',
+  description: 'Sends OpenClaw conversation events to a webhook API',
+
   configSchema: {
     type: 'object',
-    additionalProperties: false,
     properties: {
-      dataDir: { type: 'string' },
+      apiKey: { type: 'string' },
+      contextEnabled: { type: 'boolean', default: false },
     },
   },
 
   register(api: any) {
-    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;
-      }
+    const config: WebhookConfig = {
+      apiKey: api.pluginConfig?.apiKey,
+      contextEnabled: api.pluginConfig?.contextEnabled ?? false,
+    };
 
-      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: store.append failed: ${String(err)}`);
-          });
-        },
-      });
-    }
+    const logger = api.logger;
 
-    // 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: () => {},
-      });
+    if (!config.apiKey) {
+      logger.warn('[webhook] Missing apiKey - events will not be sent');
     }
 
-    api.logger.info(`ekai-contexto: storing events to ${dataDir}`);
+    logger.info(`[webhook] Plugin registered, baseUrl: ${WEBHOOK_URL_BASE}`);
+
+    // --- User input (raw inbound message) ---
+    // Using api.on() which pushes directly to typedHooks (runtime).
+    // api.registerHook() only adds to the catalog and requires config.hooks.internal.enabled.
+    api.on('message_received', async (event: any, ctx: any) => {
+      if (!config.apiKey) return;
+
+      const sessionKey = ctx?.sessionKey || 'unknown';
+      const payload = buildPayload(
+        'message',
+        'received',
+        sessionKey,
+        {
+          from: event?.from,
+          timestamp: event?.timestamp,
+          provider: event?.metadata?.provider,
+          surface: event?.metadata?.surface,
+          threadId: event?.metadata?.threadId,
+          channelName: event?.metadata?.channelName,
+          senderId: event?.metadata?.senderId,
+          senderName: event?.metadata?.senderName,
+          senderUsername: event?.metadata?.senderUsername,
+          messageId: event?.metadata?.messageId,
+        },
+        undefined,
+        {
+          content: event?.content,
+        }
+      );
+
+      sendWebhook(config, payload, logger);
+    });
+
+  // --- LLM Raw Output (as soon as the model finishes generating) ---
+  api.on('llm_output', async (event: any, ctx: any) => {
+    if (!config.apiKey) return;
+
+    // ctx usually contains the session metadata in the Plugin API
+    const sessionKey = ctx?.sessionKey || 'unknown';
+
+    const payload = buildPayload(
+      'llm',           // Type: LLM generation
+      'output',        // Action: model output received
+      sessionKey,
+      {
+        model: event?.model,            // The model used (e.g., 'gpt-4o')
+        usage: {
+          prompt_tokens: event?.usage?.promptTokens,
+          completion_tokens: event?.usage?.completionTokens,
+          total_tokens: event?.usage?.totalTokens
+        }
+      },
+      undefined,
+      {
+        content: event?.assistantText,  // The actual text generated by the AI
+      }
+    );
+
+    sendWebhook(config, payload, logger);
+  });
+
+    // --- Compaction events ---
+    api.on('before_compaction', async (event: any, ctx: any) => {
+      if (!config.apiKey) return;
+
+      const sessionKey = ctx?.sessionKey || 'unknown';
+      const payload = buildPayload(
+        'session',
+        'compact:before',
+        sessionKey,
+        {
+          messageCount: event?.messageCount,
+          tokenCount: event?.tokenCount,
+        }
+      );
+
+      sendWebhook(config, payload, logger);
+    });
+
+    api.on('after_compaction', async (event: any, ctx: any) => {
+      if (!config.apiKey) return;
+
+      const sessionKey = ctx?.sessionKey || 'unknown';
+      const payload = buildPayload(
+        'session',
+        'compact:after',
+        sessionKey,
+        {
+          summary: event?.summary?.slice(0, 2000),
+          originalMessageCount: event?.originalMessageCount,
+          compactedMessageCount: event?.compactedMessageCount,
+        }
+      );
+
+      sendWebhook(config, payload, logger);
+    });
+
+    logger.info('[webhook] All hooks registered via api.on()');
   },
 };
+
+export default webhookPlugin;