@egoai/platform 0.1.0

package/src/brain.ts

@@ -0,0 +1,584 @@
+/**
+ * Brain — Second Brain (Mnemo) hooks for the platform plugin.
+ *
+ * Hooks:
+ *   1. before_prompt_build — RAG injection: keyword-matches brain/index.md
+ *      against the user's prompt and prepends relevant wiki pages.
+ *   2. message_received — buffers user message content in memory.
+ *   3. agent_end — appends the turn (user + assistant) to an append-only
+ *      session conversation file: brain/conversations/{sessionId}.md
+ *   4. before_reset — queues the finished session for extraction processing.
+ *
+ * Conversation files are append-only markdown, one per session. Turns are
+ * appended as they happen. No per-turn log.md writes — log.md is reserved
+ * for significant events (ingests, wiki updates, session summaries).
+ *
+ * All operations are non-fatal: errors are logged, never thrown.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+import type { PluginLogger } from "openclaw/plugin-sdk";
+
+// ---------------------------------------------------------------------------
+// Hook event/context types (mirrors openclaw SDK .d.ts)
+// ---------------------------------------------------------------------------
+
+type AgentContext = {
+  runId?: string;
+  agentId?: string;
+  sessionKey?: string;
+  sessionId?: string;
+  workspaceDir?: string;
+  channelId?: string;
+  trigger?: string;
+};
+
+type BeforePromptBuildEvent = {
+  prompt: string;
+  messages: unknown[];
+};
+
+type BeforePromptBuildResult = {
+  systemPrompt?: string;
+  prependContext?: string;
+  prependSystemContext?: string;
+  appendSystemContext?: string;
+};
+
+type MessageReceivedEvent = {
+  from: string;
+  content: string;
+  timestamp?: number;
+  metadata?: Record<string, unknown>;
+};
+
+type MessageSentEvent = {
+  to: string;
+  content: string;
+  success: boolean;
+  error?: string;
+};
+
+type MessageContext = {
+  channelId: string;
+  accountId?: string;
+  conversationId?: string;
+};
+
+type AgentEndEvent = {
+  messages: unknown[];
+  success: boolean;
+  error?: string;
+  durationMs?: number;
+};
+
+type BeforeResetEvent = {
+  sessionFile?: string;
+  messages?: unknown[];
+  reason?: string;
+};
+
+type SessionEndEvent = {
+  sessionId: string;
+  sessionKey?: string;
+  messageCount: number;
+  durationMs?: number;
+};
+
+type SessionContext = {
+  agentId?: string;
+  sessionId: string;
+  sessionKey?: string;
+};
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const STOP_WORDS = new Set([
+  "the", "and", "for", "are", "but", "not", "you", "all", "can",
+  "her", "was", "one", "our", "out", "has", "have", "had", "this",
+  "that", "with", "from", "they", "been", "said", "each", "which",
+  "their", "will", "other", "about", "many", "then", "them", "these",
+  "some", "would", "make", "like", "into", "could", "time", "very",
+  "when", "what", "your", "how", "been", "just", "know", "take",
+  "people", "come", "could", "than", "look", "only", "also", "over",
+]);
+
+const MAX_PAGES = 5;
+const PAGE_TRUNCATE_CHARS = 2000;
+const CONV_SECTION_CHARS = 1000;
+
+// ---------------------------------------------------------------------------
+// State
+// ---------------------------------------------------------------------------
+
+/** Map key → workspaceDir, populated by before_prompt_build. */
+const workspaceCache = new Map<string, string>();
+
+/** Buffer last user message per conversationId for pairing with agent_end. */
+const messageBuffer = new Map<string, { content: string; timestamp: number }>();
+
+/** Track which sessions have had their frontmatter written. */
+const initializedSessions = new Set<string>();
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function today(): string {
+  return new Date().toISOString().split("T")[0];
+}
+
+function now(): string {
+  return new Date().toISOString();
+}
+
+function timeOnly(): string {
+  return new Date().toISOString().split("T")[1].replace("Z", "").split(".")[0];
+}
+
+function truncate(text: string, maxLen = 300): string {
+  if (!text || text.length <= maxLen) return text || "";
+  return text.slice(0, maxLen) + "...";
+}
+
+function readSafe(filePath: string): string {
+  try {
+    return fs.readFileSync(filePath, "utf-8");
+  } catch {
+    return "";
+  }
+}
+
+function extractKeywords(text: string): string[] {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, " ")
+    .split(/\s+/)
+    .filter((w) => w.length >= 3 && !STOP_WORDS.has(w));
+}
+
+function resolveBrainDir(ctx: AgentContext): string | null {
+  if (ctx.workspaceDir) {
+    const brainDir = path.join(ctx.workspaceDir, "brain");
+    if (fs.existsSync(brainDir)) return brainDir;
+  }
+  return null;
+}
+
+/**
+ * Build a short session filename from sessionId.
+ * Uses first 8 chars of the UUID for readability.
+ */
+function sessionFilename(sessionId: string): string {
+  const short = sessionId.slice(0, 8);
+  return `${today()}--${short}.md`;
+}
+
+/**
+ * Get or create the append-only conversation file for a session.
+ * Writes frontmatter on first access, then returns the path.
+ */
+function ensureSessionFile(
+  brainDir: string,
+  ctx: AgentContext,
+): string {
+  const convDir = path.join(brainDir, "conversations");
+  if (!fs.existsSync(convDir)) {
+    fs.mkdirSync(convDir, { recursive: true });
+  }
+
+  const sid = ctx.sessionId || "unknown";
+  const filename = sessionFilename(sid);
+  const filePath = path.join(convDir, filename);
+
+  // Write frontmatter once per session
+  if (!initializedSessions.has(sid) && !fs.existsSync(filePath)) {
+    const channel = ctx.channelId || "tui";
+    const frontmatter = [
+      `---`,
+      `type: conversation`,
+      `sessionId: ${sid}`,
+      `sessionKey: ${ctx.sessionKey || "unknown"}`,
+      `channel: ${channel}`,
+      `started: ${now()}`,
+      `---`,
+      "",
+    ].join("\n");
+    fs.writeFileSync(filePath, frontmatter, "utf-8");
+    initializedSessions.add(sid);
+  } else if (!initializedSessions.has(sid) && fs.existsSync(filePath)) {
+    // File exists from a prior gateway restart — just mark as initialized
+    initializedSessions.add(sid);
+  }
+
+  return filePath;
+}
+
+/**
+ * Append a single turn to the session conversation file.
+ */
+function appendTurn(
+  brainDir: string,
+  ctx: AgentContext,
+  userContent: string,
+  assistantContent: string,
+): string {
+  const filePath = ensureSessionFile(brainDir, ctx);
+  const time = timeOnly();
+
+  const turnBlock = [
+    "",
+    `**User** (${time}): ${truncate(userContent)}`,
+    `**Mnemo** (${time}): ${truncate(assistantContent)}`,
+    "",
+    "---",
+    "",
+  ].join("\n");
+
+  fs.appendFileSync(filePath, turnBlock, "utf-8");
+
+  return path.basename(filePath);
+}
+
+// ---------------------------------------------------------------------------
+// Index parsing + keyword matching
+// ---------------------------------------------------------------------------
+
+type IndexEntry = { path: string; keywords: string };
+
+function parseIndex(indexContent: string): IndexEntry[] {
+  const entries: IndexEntry[] = [];
+  for (const line of indexContent.split("\n")) {
+    const match = line.match(/\[\[([^\]|]+)(?:\|[^\]]+)?\]\]\s*[-—]\s*(.+)/);
+    if (match) {
+      entries.push({ path: match[1], keywords: match[2].toLowerCase() });
+    }
+  }
+  return entries;
+}
+
+function findRelevantPages(
+  indexEntries: IndexEntry[],
+  messageKeywords: string[],
+): IndexEntry[] {
+  const scored = indexEntries.map((entry) => {
+    let score = 0;
+    for (const kw of messageKeywords) {
+      if (entry.keywords.includes(kw)) score += 1;
+    }
+    return { ...entry, score };
+  });
+
+  return scored
+    .filter((e) => e.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, MAX_PAGES);
+}
+
+function getRecentConversations(brainDir: string): string {
+  const convDir = path.join(brainDir, "conversations");
+  if (!fs.existsSync(convDir)) return "";
+
+  try {
+    const files = fs
+      .readdirSync(convDir)
+      .filter((f) => f.endsWith(".md") && f !== "index.md")
+      .sort()
+      .slice(-3);
+
+    return files
+      .map((f) => readSafe(path.join(convDir, f)))
+      .filter(Boolean)
+      .join("\n\n---\n\n");
+  } catch {
+    return "";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Hook handlers
+// ---------------------------------------------------------------------------
+
+/**
+ * before_prompt_build — inject brain context into the agent's system prompt.
+ *
+ * Two responsibilities:
+ *   1. RAG: keyword-match wiki pages and inject as context
+ *   2. Pending work nudge: if there are unprocessed extractions, remind the agent
+ */
+export function handleBeforePromptBuild(
+  event: BeforePromptBuildEvent,
+  ctx: AgentContext,
+  logger?: PluginLogger,
+): BeforePromptBuildResult | void {
+  try {
+    const brainDir = resolveBrainDir(ctx);
+    if (!brainDir) return;
+
+    // Cache workspace for other hooks
+    if (ctx.channelId && ctx.workspaceDir) {
+      workspaceCache.set(ctx.channelId, ctx.workspaceDir);
+    }
+    if (ctx.agentId && ctx.workspaceDir) {
+      workspaceCache.set(`agent:${ctx.agentId}`, ctx.workspaceDir);
+    }
+
+    const sections: string[] = [];
+
+    // --- RAG: keyword match wiki pages ---
+    const prompt = event.prompt || "";
+    if (prompt.trim()) {
+      const indexContent = readSafe(path.join(brainDir, "index.md"));
+      if (indexContent) {
+        const keywords = extractKeywords(prompt);
+        if (keywords.length > 0) {
+          const indexEntries = parseIndex(indexContent);
+          const matches = findRelevantPages(indexEntries, keywords);
+          logger?.info(`brain: ${keywords.length} keywords, ${indexEntries.length} index entries, ${matches.length} matches`);
+
+          const pageContents = matches
+            .map((m) => {
+              const content = readSafe(path.join(brainDir, m.path + ".md"));
+              if (!content) return null;
+              const truncated =
+                content.length > PAGE_TRUNCATE_CHARS
+                  ? content.slice(0, PAGE_TRUNCATE_CHARS) + "\n...(truncated)"
+                  : content;
+              return `### [[${m.path}]]\n${truncated}`;
+            })
+            .filter(Boolean);
+
+          if (pageContents.length > 0) {
+            sections.push(
+              "The following pages from your knowledge base are relevant to this query:",
+              "",
+              ...(pageContents as string[]),
+            );
+            logger?.info(`brain: injecting ${pageContents.length} wiki pages as context`);
+          }
+        }
+      }
+    }
+
+    // --- Pending work nudge ---
+    const pendingPath = path.join(brainDir, ".pending-extractions.json");
+    try {
+      const raw = readSafe(pendingPath);
+      if (raw) {
+        const pending = JSON.parse(raw);
+        if (Array.isArray(pending)) {
+          const unprocessed = pending.filter(
+            (e: { processed?: boolean }) => !e.processed,
+          );
+          if (unprocessed.length > 0) {
+            sections.push(
+              "",
+              `**Pending work:** You have ${unprocessed.length} unprocessed conversation(s) in \`.pending-extractions.json\`. ` +
+              `Review them and extract any noteworthy entities or concepts into wiki pages. ` +
+              `Mark each entry as \`"processed": true\` when done.`,
+            );
+            logger?.info(`brain: nudging agent about ${unprocessed.length} pending extractions`);
+          }
+        }
+      }
+    } catch {
+      // non-fatal
+    }
+
+    if (sections.length === 0) return;
+
+    const context = [
+      "--- SECOND BRAIN CONTEXT ---",
+      ...sections,
+      "--- END BRAIN CONTEXT ---",
+    ].join("\n");
+
+    return { prependContext: context };
+  } catch (err) {
+    logger?.warn(`brain: before_prompt_build error: ${err}`);
+  }
+}
+
+/**
+ * message_received — buffer the user's message for pairing with agent_end.
+ */
+export function handleMessageReceived(
+  event: MessageReceivedEvent,
+  ctx: MessageContext,
+  logger?: PluginLogger,
+): void {
+  try {
+    const content = event.content?.trim();
+    if (!content) return;
+
+    const key = ctx.conversationId || ctx.channelId || "default";
+    messageBuffer.set(key, { content, timestamp: Date.now() });
+    // Also buffer under a generic key that agent_end can find
+    messageBuffer.set("_last", { content, timestamp: Date.now() });
+
+    logger?.info(`brain: buffered user message for ${key}`);
+  } catch (err) {
+    logger?.warn(`brain: message_received error: ${err}`);
+  }
+}
+
+/**
+ * message_sent — pair with buffered user message and log the turn.
+ * Only fires for channel messages (not TUI). Kept as a fallback.
+ */
+export function handleMessageSent(
+  _event: MessageSentEvent,
+  _ctx: MessageContext,
+  _logger?: PluginLogger,
+): void {
+  // message_sent does not fire for TUI — agent_end handles that.
+  // This is kept for channel messages (Discord, Telegram, etc.)
+  // if they're ever connected. No-op for now.
+}
+
+/**
+ * agent_end — append the turn to the session's conversation file.
+ *
+ * Fires for all agent runs including TUI. Extracts the last user +
+ * assistant messages and appends them to brain/conversations/{sessionId}.md
+ */
+export function handleAgentEnd(
+  event: AgentEndEvent,
+  ctx: AgentContext,
+  logger?: PluginLogger,
+): void {
+  try {
+    if (!event.success) return;
+
+    const brainDir = resolveBrainDir(ctx);
+    if (!brainDir) return;
+
+    const messages = event.messages || [];
+
+    // Use the buffered user message from message_received — it has the
+    // clean user input before any prependContext injection.
+    const buffered = messageBuffer.get("_last");
+    const lastUserContent = buffered?.content || "";
+    if (buffered) messageBuffer.delete("_last");
+
+    // Find last assistant message from event.messages
+    let lastAssistantContent = "";
+    for (let i = messages.length - 1; i >= 0; i--) {
+      const msg = messages[i] as { role?: string; content?: string | Array<{ text?: string }> };
+      if (msg?.role !== "assistant") continue;
+
+      let content = "";
+      if (typeof msg.content === "string") {
+        content = msg.content.trim();
+      } else if (Array.isArray(msg.content)) {
+        content = msg.content
+          .filter((b): b is { text: string } => typeof b === "object" && !!b?.text)
+          .map((b) => b.text)
+          .join("\n")
+          .trim();
+      }
+      if (!content) continue;
+
+      lastAssistantContent = content.replace(/^\[\[reply_to_current\]\]\s*/i, "");
+      break;
+    }
+
+    if (!lastUserContent || !lastAssistantContent) return;
+
+    const filename = appendTurn(brainDir, ctx, lastUserContent, lastAssistantContent);
+    logger?.info(`brain: appended turn to conversations/${filename}`);
+  } catch (err) {
+    logger?.warn(`brain: agent_end error: ${err}`);
+  }
+}
+
+/**
+ * session_end — queue the finished session for extraction processing.
+ *
+ * Writes a single log.md entry for the session and adds it to
+ * .pending-extractions.json so the agent's Auto-Curate workflow
+ * can process it into wiki pages.
+ */
+export function handleSessionEnd(
+  event: SessionEndEvent,
+  ctx: SessionContext,
+  logger?: PluginLogger,
+): void {
+  try {
+    logger?.info(`brain: session_end fired, sessionId=${ctx.sessionId}, agentId=${ctx.agentId}`);
+
+    // Resolve workspace from cache (populated by before_prompt_build)
+    // Fall back to scanning ~/.openclaw/ if cache miss
+    const agentId = ctx.agentId;
+    let cachedWorkspace = agentId ? workspaceCache.get(`agent:${agentId}`) : undefined;
+    if (!cachedWorkspace && agentId) {
+      // Fallback: construct workspace path from agentId
+      const candidate = path.join(os.homedir(), ".openclaw", `workspace-${agentId}`);
+      if (fs.existsSync(candidate)) cachedWorkspace = candidate;
+    }
+    const brainDir = cachedWorkspace
+      ? (() => { const d = path.join(cachedWorkspace, "brain"); return fs.existsSync(d) ? d : null; })()
+      : null;
+    if (!brainDir) {
+      logger?.info(`brain: session_end — no brain dir found for agent ${agentId}, cache keys: [${[...workspaceCache.keys()].join(", ")}]`);
+      return;
+    }
+
+    const sid = ctx.sessionId || "unknown";
+    const filename = sessionFilename(sid);
+    const convPath = path.join(brainDir, "conversations", filename);
+
+    logger?.info(`brain: session_end — looking for ${convPath}, exists=${fs.existsSync(convPath)}`);
+    if (!fs.existsSync(convPath)) return;
+
+    // Count turns in the file (each "**User**" line = 1 turn)
+    const content = readSafe(convPath);
+    const turnCount = (content.match(/^\*\*User\*\*/gm) || []).length;
+    if (turnCount === 0) return;
+
+    // Write one log.md entry for the session
+    const logPath = path.join(brainDir, "log.md");
+    if (fs.existsSync(logPath)) {
+      fs.appendFileSync(
+        logPath,
+        `\n## [${today()}] session | ${turnCount} turns\n\n` +
+        `- Session: \`conversations/${filename}\`\n` +
+        `- Channel: ${(ctx.sessionKey || "").includes("platform") ? "platform" : "tui"}\n` +
+        `- Ended: ${now()}\n\n`,
+        "utf-8",
+      );
+    }
+
+    // Queue for extraction
+    const pendingPath = path.join(brainDir, ".pending-extractions.json");
+    let pending: unknown[] = [];
+    try {
+      pending = JSON.parse(readSafe(pendingPath) || "[]");
+    } catch {
+      // no-op
+    }
+    if (!Array.isArray(pending)) pending = [];
+
+    pending.push({
+      date: today(),
+      timestamp: now(),
+      sessionFile: `conversations/${filename}`,
+      turns: turnCount,
+      processed: false,
+    });
+    if (pending.length > 50) pending = pending.slice(-50);
+    fs.writeFileSync(pendingPath, JSON.stringify(pending, null, 2), "utf-8");
+
+    // Clean up session tracking
+    initializedSessions.delete(sid);
+
+    logger?.info(`brain: session ended — ${turnCount} turns queued for extraction`);
+  } catch (err) {
+    logger?.warn(`brain: before_reset error: ${err}`);
+  }
+}

package/src/channel.ts

@@ -0,0 +1,54 @@
+/**
+ * ChannelPlugin definition for platform.
+ *
+ * Per the OpenClaw SDK spec, only `id` and `setup` are required.
+ * Additional adapters (security, pairing, threading, outbound) are
+ * opt-in and not needed for a transparent relay channel.
+ */
+
+import type { ChannelGatewayContext, ChannelPlugin, OpenClawConfig } from "openclaw/plugin-sdk";
+import { resolveAccount, inspectAccount, type PlatformAccount } from "./config.js";
+import { startAccount } from "./monitor.js";
+
+export const PlatformChannel: ChannelPlugin = {
+  id: "platform",
+
+  meta: {
+    id: "platform",
+    label: "platform",
+    selectionLabel: "platform",
+    docsPath: "/channels/platform",
+    blurb: "Connect OpenClaw to character platform.",
+    aliases: ["platform"],
+  },
+
+  capabilities: {
+    chatTypes: ["direct"] as const,
+  },
+
+  threading: {
+    resolveReplyToMode: () => "all",
+  },
+
+  config: {
+    listAccountIds(cfg: OpenClawConfig): string[] {
+      const platform = cfg?.channels?.platform;
+      if (!platform?.enabled) return [];
+      return ["platform"];
+    },
+
+    resolveAccount(cfg: OpenClawConfig, accountId?: string | null): PlatformAccount {
+      return resolveAccount(cfg, accountId ?? undefined);
+    },
+
+    inspectAccount(cfg: OpenClawConfig, accountId?: string | null) {
+      return inspectAccount(cfg, accountId);
+    },
+  },
+
+  gateway: {
+    async startAccount(ctx: ChannelGatewayContext<PlatformAccount>): Promise<void> {
+      await startAccount(ctx);
+    },
+  },
+};