@ekai/contexto 0.1.0

package/openclaw.plugin.json

@@ -0,0 +1,16 @@
+{
+  "id": "ekai-contexto",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "logPath": { "type": "string" }
+    }
+  },
+  "uiHints": {
+    "logPath": {
+      "label": "Event log path",
+      "description": "Path to the JSONL event log file"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@ekai/contexto",
+  "version": "0.1.0",
+  "description": "OpenClaw plugin — captures all lifecycle events to JSONL for context, memory, and analytics",
+  "type": "module",
+  "license": "MIT",
+  "main": "src/index.ts",
+  "files": [
+    "src/",
+    "openclaw.plugin.json"
+  ],
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "ai",
+    "context",
+    "memory",
+    "lifecycle",
+    "events"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ekai-labs/ekai-gateway",
+    "directory": "integrations/openclaw"
+  },
+  "author": "Ekai Labs",
+  "scripts": {
+    "type-check": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.2"
+  },
+  "openclaw": {
+    "extensions": ["./src/index.ts"]
+  }
+}

package/src/index.ts

@@ -0,0 +1,47 @@
+import { EventLog } from './store.js';
+
+const 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;
+
+export default {
+  id: 'ekai-contexto',
+  name: 'Ekai Contexto',
+  description: 'Context engine for OpenClaw — captures lifecycle events, extensible to memory injection',
+  configSchema: {},
+
+  register(api: any) {
+    const logPath = api.resolvePath(api.pluginConfig?.logPath ?? '~/.openclaw/ekai/events.jsonl');
+    const log = new EventLog(logPath);
+
+    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)}`);
+          }
+        },
+      });
+    }
+
+    api.logger.info(`ekai-contexto: logging to ${logPath}`);
+  },
+};

package/src/store.ts

@@ -0,0 +1,56 @@
+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');
+  }
+}