@sage-protocol/openclaw-sage 0.1.3 → 0.1.4

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.1.3"
+  ".": "0.1.4"
 }

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.1.4](https://github.com/sage-protocol/openclaw-sage/compare/openclaw-sage-v0.1.3...openclaw-sage-v0.1.4) (2026-02-04)
+
+
+### Features
+
+* add support for external MCP servers from mcp-servers.toml ([d7e6283](https://github.com/sage-protocol/openclaw-sage/commit/d7e62836296fb6032e62b036b8a0900d1d384198))
+* auto-inject context at agent start ([6417254](https://github.com/sage-protocol/openclaw-sage/commit/6417254168f6307d42b54880c07cb46e62832514))
+
+
+### Bug Fixes
+
+* adding SOUL.md and rlm test ([2644710](https://github.com/sage-protocol/openclaw-sage/commit/26447107a4f40d675480f9d36b5bb9f058ed8e33))
+* pass HOME and XDG env vars to sage subprocess for auth persistence ([653ff31](https://github.com/sage-protocol/openclaw-sage/commit/653ff3135996c1e82d916794d74fe61510a5a1fd))
+
 ## [0.1.3](https://github.com/sage-protocol/openclaw-sage/compare/openclaw-sage-v0.1.2...openclaw-sage-v0.1.3) (2026-02-02)
 
 

package/README.md

@@ -25,6 +25,30 @@ The plugin auto-detects the `sage` binary from PATH. To override:
 }
 ```
 
+### Auto-Inject / Auto-Suggest
+
+This plugin uses OpenClaw's plugin hook API to inject context at the start of each agent run (`before_agent_start`).
+
+Available config fields:
+
+```json
+{
+  "autoInjectContext": true,
+  "autoSuggestSkills": true,
+  "suggestLimit": 3,
+  "minPromptLen": 12,
+  "maxPromptBytes": 16384
+}
+```
+
+### Avoiding Double Injection
+
+If you also enabled Sage's OpenClaw *internal hook* (installed by `sage init --openclaw`), both the hook and this plugin can inject Sage context.
+
+- Recommended: keep the plugin injection on, and disable the internal hook injection via `SAGE_OPENCLAW_INJECT_CONTEXT=0` in your OpenClaw environment.
+
+The internal hook exists mainly for bootstrap-file injection; the plugin is the preferred place for per-run injection and suggestions.
+
 ## What It Provides
 
 Once loaded, all Sage MCP tools are available in OpenClaw:

package/SOUL.md

@@ -17,7 +17,7 @@ Prompt the user to run `sage init` and/or `sage agent quickstart` when any of th
 
 - The user asks about setup, installation, configuration, MCP tools, skills, libraries, or OpenClaw integration.
 - The session appears to be a first run (no prior mention of `sage init` / `sage agent quickstart`).
-- The user hits auth/credits/wallet friction (examples: wallet not configured, faucet needed, IPFS credits missing, library sync failing).
+- The user hits auth/credits/wallet friction (examples: wallet not configured, SXXX tokens needed, IPFS credits missing, library sync failing).
 
 ## How To Prompt (Non-Spammy)
 
@@ -31,13 +31,15 @@ If Sage is not initialized:
 
 ```text
 Run `sage init` to set up the Sage skill + MCP integration for your environment.
-After that, run `sage agent quickstart` to claim testnet tokens + IPFS credits.
+Then request SXXX tokens: `sage chat send global:agents "request tokens"`
+Then claim IPFS credits: `sage agent quickstart`
 ```
 
 If Sage is initialized but the user needs tokens/credits:
 
 ```text
-Run `sage agent quickstart` to claim testnet tokens + IPFS credits (it will also check your current status).
+Request SXXX tokens from the bot: `sage chat send global:agents "request tokens"`
+Then claim IPFS credits: `sage agent quickstart`
 ```
 
 If the user is using OpenClaw and doesn't have MCP tools:

package/openclaw.plugin.json

@@ -14,6 +14,26 @@
       "sageBinary": {
         "type": "string",
         "description": "Path to sage binary (default: auto-detect from PATH)"
+      },
+      "autoInjectContext": {
+        "type": "boolean",
+        "description": "Inject Sage tool context into the agent at start (default: true)"
+      },
+      "autoSuggestSkills": {
+        "type": "boolean",
+        "description": "Suggest relevant skills at agent start (default: true)"
+      },
+      "suggestLimit": {
+        "type": "number",
+        "description": "Max number of skill suggestions to include (default: 3)"
+      },
+      "minPromptLen": {
+        "type": "number",
+        "description": "Minimum prompt length before suggesting (default: 12)"
+      },
+      "maxPromptBytes": {
+        "type": "number",
+        "description": "Max prompt bytes forwarded to suggestion search (default: 16384)"
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sage-protocol/openclaw-sage",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Sage MCP bridge plugin for OpenClaw — prompt libraries, skills, governance, and on-chain operations",
   "main": "src/index.ts",
   "type": "module",
@@ -11,14 +11,16 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "npx --yes tsx src/mcp-bridge.test.ts"
+    "test": "node --import tsx src/mcp-bridge.test.ts"
   },
   "dependencies": {
+    "@iarna/toml": "^2.2.5",
     "@sinclair/typebox": "^0.34.0"
   },
   "devDependencies": {
-    "typescript": "^5.6.0",
-    "tsx": "^4.19.0"
+    "@types/node": "^25.2.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
   },
   "license": "MIT"
 }

package/src/index.ts

@@ -1,9 +1,37 @@
 import { Type } from "@sinclair/typebox";
-
-import { spawn } from "node:child_process";
+import { readFileSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import TOML from "@iarna/toml";
 
 import { McpBridge, type McpToolDef } from "./mcp-bridge.js";
 
+const SAGE_CONTEXT = `## Sage MCP Tools Available
+
+You have access to Sage MCP tools for prompts, skills, and knowledge discovery.
+
+### Prompt Discovery
+- \`search_prompts\` - Hybrid keyword + semantic search for prompts
+- \`list_prompts\` - Browse prompts by source (local/onchain)
+- \`get_prompt\` - Get full prompt content by key
+- \`builder_recommend\` - AI-powered prompt suggestions based on intent
+
+### Skills
+- \`search_skills\` / \`list_skills\` - Find available skills
+- \`get_skill\` - Get skill details and content
+- \`use_skill\` - Activate a skill (auto-provisions required MCP servers)
+
+### External Tools (via Hub)
+- \`hub_list_servers\` - List available MCP servers (memory, github, brave, etc.)
+- \`hub_start_server\` - Start an MCP server to gain access to its tools
+- \`hub_status\` - Check which servers are currently running
+
+### Best Practices
+1. **Search before implementing** - Use \`search_prompts\` or \`builder_recommend\` to find existing solutions
+2. **Use skills for complex tasks** - Skills bundle prompts + MCP servers for specific workflows
+3. **Start additional servers as needed** - Use \`hub_start_server\` for memory, github, brave search, etc.
+4. **Check skill requirements** - Skills may require specific MCP servers; \`use_skill\` auto-provisions them`;
+
 /**
  * Minimal type stubs for OpenClaw plugin API.
  *
@@ -27,13 +55,104 @@ type PluginApi = {
   id: string;
   name: string;
   logger: PluginLogger;
+  pluginConfig?: Record<string, unknown>;
   registerTool: (tool: unknown, opts?: { name?: string; optional?: boolean }) => void;
   registerService: (service: {
     id: string;
     start: (ctx: PluginServiceContext) => void | Promise<void>;
     stop?: (ctx: PluginServiceContext) => void | Promise<void>;
   }) => void;
-  on: (hook: string, handler: (...args: unknown[]) => void | Promise<void>) => void;
+  on: (hook: string, handler: (...args: unknown[]) => unknown | Promise<unknown>) => void;
+};
+
+function clampInt(raw: unknown, def: number, min: number, max: number): number {
+  const n = typeof raw === "string" && raw.trim() ? Number(raw) : Number(raw);
+  if (!Number.isFinite(n)) return def;
+  return Math.min(max, Math.max(min, Math.trunc(n)));
+}
+
+function truncateUtf8(s: string, maxBytes: number): string {
+  if (Buffer.byteLength(s, "utf8") <= maxBytes) return s;
+
+  let lo = 0;
+  let hi = s.length;
+  while (lo < hi) {
+    const mid = Math.ceil((lo + hi) / 2);
+    if (Buffer.byteLength(s.slice(0, mid), "utf8") <= maxBytes) lo = mid;
+    else hi = mid - 1;
+  }
+  return s.slice(0, lo);
+}
+
+function normalizePrompt(prompt: string, opts?: { maxBytes?: number }): string {
+  const trimmed = prompt.trim();
+  if (!trimmed) return "";
+  const maxBytes = clampInt(opts?.maxBytes, 16_384, 512, 65_536);
+  return truncateUtf8(trimmed, maxBytes);
+}
+
+function extractJsonFromMcpResult(result: unknown): unknown {
+  const anyResult = result as any;
+  if (!anyResult || typeof anyResult !== "object") return undefined;
+
+  // Sage MCP tools typically return { content: [{ type: 'text', text: '...json...' }], isError?: bool }
+  const text =
+    Array.isArray(anyResult.content) && anyResult.content.length
+      ? anyResult.content
+          .map((c: any) => (c && typeof c.text === "string" ? c.text : ""))
+          .filter(Boolean)
+          .join("\n")
+      : undefined;
+
+  if (!text) return undefined;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}
+
+type SkillSearchResult = {
+  key?: string;
+  name?: string;
+  description?: string;
+  source?: string;
+  library?: string;
+  mcpServers?: string[];
+};
+
+function formatSkillSuggestions(results: SkillSearchResult[], limit: number): string {
+  const items = results
+    .filter((r) => r && typeof r.key === "string" && r.key.trim())
+    .slice(0, limit);
+  if (!items.length) return "";
+
+  const lines: string[] = [];
+  lines.push("## Suggested Skills");
+  lines.push("");
+  for (const r of items) {
+    const key = r.key!.trim();
+    const desc = typeof r.description === "string" ? r.description.trim() : "";
+    const origin = typeof r.library === "string" && r.library.trim() ? ` (from ${r.library.trim()})` : "";
+    const servers = Array.isArray(r.mcpServers) && r.mcpServers.length ? ` — requires: ${r.mcpServers.join(", ")}` : "";
+    lines.push(`- \`use_skill\` \`${key}\`${origin}${desc ? `: ${desc}` : ""}${servers}`);
+  }
+  return lines.join("\n");
+}
+
+/** Custom server configuration from mcp-servers.toml */
+type CustomServerConfig = {
+  id: string;
+  name: string;
+  description?: string;
+  enabled: boolean;
+  source: {
+    type: "npx" | "node" | "binary";
+    package?: string;
+    path?: string;
+  };
+  extra_args?: string[];
+  env?: Record<string, string>;
 };
 
 /**
@@ -98,205 +217,229 @@ function toToolResult(mcpResult: unknown) {
   };
 }
 
-// ── Plugin Definition ────────────────────────────────────────────────────────
-
-let bridge: McpBridge | null = null;
-
-function extractText(input: unknown): string {
-  if (typeof input === "string") return input;
-  if (!input || typeof input !== "object") return "";
-
-  const obj = input as any;
-  const direct = [obj.text, obj.content, obj.prompt, obj.message, obj.input];
-  for (const c of direct) {
-    if (typeof c === "string" && c.trim()) return c.trim();
-  }
+/**
+ * Load custom server configurations from ~/.config/sage/mcp-servers.toml
+ */
+function loadCustomServers(): CustomServerConfig[] {
+  const configPath = join(homedir(), ".config", "sage", "mcp-servers.toml");
 
-  if (obj.message && typeof obj.message === "object") {
-    const msg = obj.message as any;
-    if (typeof msg.text === "string" && msg.text.trim()) return msg.text.trim();
-    if (typeof msg.content === "string" && msg.content.trim()) return msg.content.trim();
+  if (!existsSync(configPath)) {
+    return [];
   }
 
-  // Transcript-style: [{role, content}]
-  if (Array.isArray(obj.messages)) {
-    for (let i = obj.messages.length - 1; i >= 0; i--) {
-      const m = obj.messages[i];
-      if (!m || typeof m !== "object") continue;
-      const mm = m as any;
-      if (typeof mm.content === "string" && mm.content.trim()) return mm.content.trim();
-      if (typeof mm.text === "string" && mm.text.trim()) return mm.text.trim();
-      if (Array.isArray(mm.content)) {
-        const text = mm.content
-          .map((b: any) => (b?.type === "text" ? b?.text : ""))
-          .filter(Boolean)
-          .join("\n");
-        if (text.trim()) return text.trim();
-      }
+  try {
+    const content = readFileSync(configPath, "utf8");
+    const config = TOML.parse(content) as {
+      custom?: Record<string, {
+        id: string;
+        name: string;
+        description?: string;
+        enabled: boolean;
+        source: { type: string; package?: string; path?: string };
+        extra_args?: string[];
+        env?: Record<string, string>;
+      }>;
+    };
+
+    if (!config.custom) {
+      return [];
     }
-  }
-
-  return "";
-}
 
-function lastAssistantText(input: unknown): string {
-  if (!input || typeof input !== "object") return "";
-  const obj = input as any;
-
-  const candidates = [obj.final, obj.output, obj.result, obj.response];
-  for (const c of candidates) {
-    const t = extractText(c);
-    if (t) return t;
+    return Object.values(config.custom)
+      .filter((s) => s.enabled)
+      .map((s) => ({
+        id: s.id,
+        name: s.name,
+        description: s.description,
+        enabled: s.enabled,
+        source: {
+          type: s.source.type as "npx" | "node" | "binary",
+          package: s.source.package,
+          path: s.source.path,
+        },
+        extra_args: s.extra_args,
+        env: s.env,
+      }));
+  } catch (err) {
+    console.error(`Failed to parse mcp-servers.toml: ${err}`);
+    return [];
   }
+}
 
-  if (Array.isArray(obj.messages)) {
-    for (let i = obj.messages.length - 1; i >= 0; i--) {
-      const m = obj.messages[i];
-      if (!m || typeof m !== "object") continue;
-      const mm = m as any;
-      if (mm.role === "assistant") {
-        const t = extractText(mm);
-        if (t) return t;
-      }
-    }
+/**
+ * Create command and args for spawning an external server
+ */
+function getServerCommand(server: CustomServerConfig): { command: string; args: string[] } {
+  switch (server.source.type) {
+    case "npx":
+      return {
+        command: "npx",
+        args: ["-y", server.source.package!, ...(server.extra_args || [])],
+      };
+    case "node":
+      return {
+        command: "node",
+        args: [server.source.path!, ...(server.extra_args || [])],
+      };
+    case "binary":
+      return {
+        command: server.source.path!,
+        args: server.extra_args || [],
+      };
+    default:
+      throw new Error(`Unknown source type: ${server.source.type}`);
   }
-
-  return "";
 }
 
-function toStringOrEmpty(v: unknown): string {
-  if (typeof v === "string") return v;
-  if (typeof v === "number") return String(v);
-  if (typeof v === "boolean") return v ? "1" : "0";
-  return "";
-}
+// ── Plugin Definition ────────────────────────────────────────────────────────
 
-function fireAndForget(cmd: string, args: string[], env: Record<string, string>): void {
-  try {
-    const p = spawn(cmd, args, {
-      env: { ...process.env, ...env },
-      stdio: "ignore",
-      detached: true,
-    });
-    p.unref();
-  } catch {
-    // ignore
-  }
-}
+let sageBridge: McpBridge | null = null;
+const externalBridges: Map<string, McpBridge> = new Map();
 
 const plugin = {
   id: "openclaw-sage",
   name: "Sage Protocol",
-  version: "0.1.2",
+  version: "0.2.0",
   description:
-    "Sage MCP tools for prompt libraries, skills, governance, and on-chain operations",
+    "Sage MCP tools for prompt libraries, skills, governance, and on-chain operations (including external servers)",
 
   register(api: PluginApi) {
-    bridge = new McpBridge("sage", ["mcp", "start"]);
-
-    bridge.on("log", (line: string) => api.logger.info(`[sage-mcp] ${line}`));
-    bridge.on("error", (err: Error) => api.logger.error(`[sage-mcp] ${err.message}`));
-
-    // RLM capture hooks (derived data): attach prompt/response pairs with OpenClaw tags.
-    api.on("message_received", async (evt: unknown) => {
-      const prompt = extractText(evt);
-      if (!prompt) return;
-
-      const e = evt as any;
-      const sessionId =
-        toStringOrEmpty(e?.sessionId) ||
-        toStringOrEmpty(e?.sessionKey) ||
-        toStringOrEmpty(e?.context?.sessionId) ||
-        toStringOrEmpty(e?.context?.sessionKey);
-      const workspaceDir = toStringOrEmpty(e?.workspaceDir) || toStringOrEmpty(e?.context?.workspaceDir);
-
-      const attrs = {
-        openclaw: {
-          hook: "message_received",
-          sessionId: toStringOrEmpty(e?.sessionId) || toStringOrEmpty(e?.context?.sessionId),
-          sessionKey: toStringOrEmpty(e?.sessionKey) || toStringOrEmpty(e?.context?.sessionKey),
-          channel: toStringOrEmpty(e?.channel) || toStringOrEmpty(e?.context?.commandSource),
-          senderId: toStringOrEmpty(e?.senderId) || toStringOrEmpty(e?.context?.senderId),
-        },
-      };
-
-      fireAndForget("sage", ["capture", "hook", "prompt"], {
-        SAGE_SOURCE: "openclaw",
-        OPENCLAW: "1",
-        PROMPT: prompt,
-        SAGE_SESSION_ID: sessionId,
-        SAGE_WORKSPACE: workspaceDir,
-        SAGE_MODEL: toStringOrEmpty(e?.model) || toStringOrEmpty(e?.context?.model),
-        SAGE_PROVIDER: toStringOrEmpty(e?.provider) || toStringOrEmpty(e?.context?.provider),
-        SAGE_CAPTURE_ATTRIBUTES_JSON: JSON.stringify(attrs),
-      });
-    });
-
-    api.on("agent_end", async (evt: unknown) => {
-      const response = lastAssistantText(evt);
-      if (!response) return;
-
-      const e = evt as any;
-      const tokensIn =
-        toStringOrEmpty(e?.usage?.tokens_input) ||
-        toStringOrEmpty(e?.usage?.input_tokens) ||
-        toStringOrEmpty(e?.usage?.inputTokens);
-      const tokensOut =
-        toStringOrEmpty(e?.usage?.tokens_output) ||
-        toStringOrEmpty(e?.usage?.output_tokens) ||
-        toStringOrEmpty(e?.usage?.outputTokens);
-
-      fireAndForget("sage", ["capture", "hook", "response"], {
-        SAGE_SOURCE: "openclaw",
-        OPENCLAW: "1",
-        LAST_RESPONSE: response,
-        TOKENS_INPUT: tokensIn,
-        TOKENS_OUTPUT: tokensOut,
-      });
+    const pluginCfg = api.pluginConfig ?? {};
+    const sageBinary = typeof pluginCfg.sageBinary === "string" && pluginCfg.sageBinary.trim()
+      ? pluginCfg.sageBinary.trim()
+      : "sage";
+
+    const autoInject = pluginCfg.autoInjectContext !== false;
+    const autoSuggest = pluginCfg.autoSuggestSkills !== false;
+    const suggestLimit = clampInt(pluginCfg.suggestLimit, 3, 1, 10);
+    const minPromptLen = clampInt(pluginCfg.minPromptLen, 12, 0, 500);
+    const maxPromptBytes = clampInt(pluginCfg.maxPromptBytes, 16_384, 512, 65_536);
+
+    // Main sage MCP bridge - pass HOME to ensure auth state is found
+    sageBridge = new McpBridge(sageBinary, ["mcp", "start"], {
+      HOME: homedir(),
+      PATH: process.env.PATH || "",
+      USER: process.env.USER || "",
+      XDG_CONFIG_HOME: process.env.XDG_CONFIG_HOME || join(homedir(), ".config"),
+      XDG_DATA_HOME: process.env.XDG_DATA_HOME || join(homedir(), ".local", "share"),
     });
+    sageBridge.on("log", (line: string) => api.logger.info(`[sage-mcp] ${line}`));
+    sageBridge.on("error", (err: Error) => api.logger.error(`[sage-mcp] ${err.message}`));
 
     api.registerService({
       id: "sage-mcp-bridge",
       start: async (ctx) => {
         ctx.logger.info("Starting Sage MCP bridge...");
+
+        // Start the main sage bridge
         try {
-          await bridge!.start();
+          await sageBridge!.start();
           ctx.logger.info("Sage MCP bridge ready");
 
-          const tools = await bridge!.listTools();
-          ctx.logger.info(`Discovered ${tools.length} MCP tools`);
+          const tools = await sageBridge!.listTools();
+          ctx.logger.info(`Discovered ${tools.length} internal MCP tools`);
 
           for (const tool of tools) {
-            registerMcpTool(api, tool);
+            registerMcpTool(api, "sage", sageBridge!, tool);
           }
         } catch (err) {
           ctx.logger.error(
-            `Failed to start MCP bridge: ${err instanceof Error ? err.message : String(err)}`,
+            `Failed to start sage MCP bridge: ${err instanceof Error ? err.message : String(err)}`,
           );
         }
+
+        // Load and start external servers
+        const customServers = loadCustomServers();
+        ctx.logger.info(`Found ${customServers.length} custom external servers`);
+
+        for (const server of customServers) {
+          try {
+            ctx.logger.info(`Starting external server: ${server.name} (${server.id})`);
+
+            const { command, args } = getServerCommand(server);
+            const bridge = new McpBridge(command, args, server.env);
+
+            bridge.on("log", (line: string) => ctx.logger.info(`[${server.id}] ${line}`));
+            bridge.on("error", (err: Error) => ctx.logger.error(`[${server.id}] ${err.message}`));
+
+            await bridge.start();
+            externalBridges.set(server.id, bridge);
+
+            const tools = await bridge.listTools();
+            ctx.logger.info(`[${server.id}] Discovered ${tools.length} tools`);
+
+            for (const tool of tools) {
+              registerMcpTool(api, server.id.replace(/-/g, "_"), bridge, tool);
+            }
+          } catch (err) {
+            ctx.logger.error(
+              `Failed to start ${server.name}: ${err instanceof Error ? err.message : String(err)}`,
+            );
+          }
+        }
       },
       stop: async (ctx) => {
-        ctx.logger.info("Stopping Sage MCP bridge...");
-        await bridge?.stop();
+        ctx.logger.info("Stopping Sage MCP bridges...");
+
+        // Stop external bridges
+        for (const [id, bridge] of externalBridges) {
+          ctx.logger.info(`Stopping ${id}...`);
+          await bridge.stop();
+        }
+        externalBridges.clear();
+
+        // Stop main sage bridge
+        await sageBridge?.stop();
       },
     });
+
+    // Auto-inject context and suggestions at agent start.
+    // This uses OpenClaw's plugin hook API (not internal hooks).
+    api.on("before_agent_start", async (event: any) => {
+      const prompt = normalizePrompt(typeof event?.prompt === "string" ? event.prompt : "", {
+        maxBytes: maxPromptBytes,
+      });
+      if (!prompt || prompt.length < minPromptLen) {
+        return autoInject ? { prependContext: SAGE_CONTEXT } : undefined;
+      }
+
+      let suggestBlock = "";
+      if (autoSuggest && sageBridge) {
+        try {
+          const raw = await sageBridge.callTool("search_skills", {
+            query: prompt,
+            source: "all",
+            limit: Math.max(20, suggestLimit),
+          });
+          const json = extractJsonFromMcpResult(raw) as any;
+          const results = Array.isArray(json?.results) ? (json.results as SkillSearchResult[]) : [];
+          suggestBlock = formatSkillSuggestions(results, suggestLimit);
+        } catch {
+          // Ignore suggestion failures; context injection should still work.
+        }
+      }
+
+      const parts: string[] = [];
+      if (autoInject) parts.push(SAGE_CONTEXT);
+      if (suggestBlock) parts.push(suggestBlock);
+
+      if (!parts.length) return undefined;
+      return { prependContext: parts.join("\n\n") };
+    });
   },
 };
 
-function registerMcpTool(api: PluginApi, tool: McpToolDef) {
-  const name = `sage_${tool.name}`;
+function registerMcpTool(api: PluginApi, prefix: string, bridge: McpBridge, tool: McpToolDef) {
+  const name = `${prefix}_${tool.name}`;
   const schema = mcpSchemaToTypebox(tool.inputSchema);
 
   api.registerTool(
     {
       name,
-      label: `Sage: ${tool.name}`,
-      description: tool.description ?? `Sage MCP tool: ${tool.name}`,
+      label: `${prefix}: ${tool.name}`,
+      description: tool.description ?? `MCP tool: ${prefix}/${tool.name}`,
       parameters: schema,
       execute: async (_toolCallId: string, params: Record<string, unknown>) => {
-        if (!bridge) {
-          return toToolResult({ error: "MCP bridge not initialized" });
-        }
         try {
           const result = await bridge.callTool(tool.name, params);
           return toToolResult(result);
@@ -312,3 +455,10 @@ function registerMcpTool(api: PluginApi, tool: McpToolDef) {
 }
 
 export default plugin;
+
+export const __test = {
+  SAGE_CONTEXT,
+  normalizePrompt,
+  extractJsonFromMcpResult,
+  formatSkillSuggestions,
+};

package/src/mcp-bridge.test.ts

@@ -4,6 +4,7 @@ import { resolve } from "node:path";
 
 import { McpBridge } from "./mcp-bridge.js";
 import plugin from "./index.js";
+import { __test } from "./index.js";
 
 function addSageDebugBinToPath() {
   // Ensure the `sage` binary used by the plugin resolves to this repo's build.
@@ -79,3 +80,53 @@ test("OpenClaw plugin registers MCP tools via sage mcp start", async () => {
     });
   }
 });
+
+test("OpenClaw plugin registers before_agent_start hook and returns prependContext", async () => {
+  const hooks: Record<string, any> = {};
+
+  const api = {
+    id: "t",
+    name: "t",
+    pluginConfig: {},
+    logger: {
+      info: (_: string) => {},
+      warn: (_: string) => {},
+      error: (_: string) => {},
+    },
+    registerTool: (_tool: any) => {},
+    registerService: (_svc: any) => {},
+    on: (hook: string, handler: any) => {
+      hooks[hook] = handler;
+    },
+  };
+
+  plugin.register(api as any);
+  assert.ok(typeof hooks.before_agent_start === "function", "expected before_agent_start hook");
+
+  const result = await hooks.before_agent_start({ prompt: "build an mcp server" });
+  assert.ok(result && typeof result === "object");
+  assert.ok(
+    typeof result.prependContext === "string" && result.prependContext.includes("Sage MCP Tools Available"),
+    "expected prependContext with Sage tool context",
+  );
+});
+
+test("formatSkillSuggestions formats stable markdown", () => {
+  const out = __test.formatSkillSuggestions(
+    [
+      {
+        key: "bug-bounty",
+        name: "Bug Bounty",
+        description: "Recon, scanning, API testing",
+        source: "installed",
+        mcpServers: ["zap"],
+      },
+      { key: "", name: "skip" },
+    ],
+    3,
+  );
+
+  assert.ok(out.includes("## Suggested Skills"));
+  assert.ok(out.includes("`use_skill` `bug-bounty`"));
+  assert.ok(out.includes("requires: zap"));
+});

package/src/mcp-bridge.ts

@@ -45,6 +45,7 @@ export class McpBridge extends EventEmitter {
   constructor(
     private command: string,
     private args: string[],
+    private env?: Record<string, string>,
   ) {
     super();
   }
@@ -94,7 +95,7 @@ export class McpBridge extends EventEmitter {
     return new Promise((resolve, reject) => {
       const proc = spawn(this.command, this.args, {
         stdio: ["pipe", "pipe", "pipe"],
-        env: { ...process.env },
+        env: { ...process.env, ...this.env },
       });
 
       proc.on("error", (err) => {

package/src/rlm-capture.e2e.test.ts

@@ -0,0 +1,255 @@
+/**
+ * E2E Test: OpenClaw RLM Capture Path
+ *
+ * Validates the OpenClaw-specific capture flow:
+ *   1. Spawn sage MCP server with isolated HOME
+ *   2. Simulate message_received hook (sage capture hook prompt)
+ *   3. Simulate agent_end hook (sage capture hook response)
+ *   4. Verify captures landed via rlm_stats MCP tool
+ *   5. Run rlm_analyze_captures and verify stats update
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { resolve } from "node:path";
+import { mkdtempSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { spawn, type ChildProcess } from "node:child_process";
+import { createInterface } from "node:readline";
+import { randomUUID } from "node:crypto";
+
+// ── Helpers ──────────────────────────────────────────────────────────
+
+const sageBin = resolve(new URL("..", import.meta.url).pathname, "..", "target", "debug", "sage");
+
+function createIsolatedHome(): string {
+  return mkdtempSync(resolve(tmpdir(), "sage-openclaw-e2e-"));
+}
+
+function isolatedEnv(tmpHome: string): Record<string, string> {
+  return {
+    ...(process.env as Record<string, string>),
+    HOME: tmpHome,
+    XDG_CONFIG_HOME: resolve(tmpHome, ".config"),
+    XDG_DATA_HOME: resolve(tmpHome, ".local/share"),
+    SAGE_HOME: resolve(tmpHome, ".sage"),
+  };
+}
+
+type JsonRpcClient = {
+  request: (method: string, params: Record<string, unknown>) => Promise<unknown>;
+  notify: (method: string, params: Record<string, unknown>) => void;
+};
+
+function createMcpClient(proc: ChildProcess): JsonRpcClient {
+  const pending = new Map<string, { resolve: (v: unknown) => void; reject: (e: Error) => void }>();
+
+  if (!proc.stdout) throw new Error("No stdout");
+
+  const rl = createInterface({ input: proc.stdout });
+  rl.on("line", (line) => {
+    let msg: any;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      return;
+    }
+    if (!msg?.id) return;
+    const id = String(msg.id);
+    const waiter = pending.get(id);
+    if (!waiter) return;
+    pending.delete(id);
+    if (msg.error) waiter.reject(new Error(msg.error.message || "MCP error"));
+    else waiter.resolve(msg.result);
+  });
+
+  return {
+    request(method, params) {
+      if (!proc.stdin?.writable) throw new Error("stdin not writable");
+      const id = randomUUID();
+      const req = { jsonrpc: "2.0", id, method, params };
+      proc.stdin.write(JSON.stringify(req) + "\n");
+      return new Promise((resolve, reject) => {
+        pending.set(id, { resolve, reject });
+      });
+    },
+    notify(method, params) {
+      if (!proc.stdin?.writable) return;
+      proc.stdin.write(JSON.stringify({ jsonrpc: "2.0", method, params }) + "\n");
+    },
+  };
+}
+
+async function callTool(
+  client: JsonRpcClient,
+  name: string,
+  args: Record<string, unknown> = {},
+): Promise<any> {
+  const result = (await client.request("tools/call", {
+    name,
+    arguments: args,
+  })) as any;
+
+  const text =
+    result?.content
+      ?.filter((c: any) => c.type === "text")
+      .map((c: any) => c.text)
+      .join("\n") ?? "";
+
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+function runCaptureCli(
+  bin: string,
+  subArgs: string[],
+  env: Record<string, string>,
+): Promise<number | null> {
+  return new Promise((resolve) => {
+    const p = spawn(bin, subArgs, {
+      env,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    p.on("close", (code) => resolve(code));
+    p.on("error", () => resolve(null));
+  });
+}
+
+// ── Tests ────────────────────────────────────────────────────────────
+
+const TIMEOUT = 60_000;
+
+test("OpenClaw capture flow: prompt + response -> rlm_stats", { timeout: TIMEOUT }, async () => {
+  const tmpHome = createIsolatedHome();
+  const env = isolatedEnv(tmpHome);
+
+  // Start MCP server
+  const proc = spawn(sageBin, ["mcp", "start"], {
+    stdio: ["pipe", "pipe", "pipe"],
+    env,
+  });
+
+  const client = createMcpClient(proc);
+
+  try {
+    // MCP handshake
+    const init = await client.request("initialize", {
+      protocolVersion: "2024-11-05",
+      capabilities: {},
+      clientInfo: { name: "openclaw-e2e-test", version: "0.0.0" },
+    });
+    assert.ok(init, "initialize should return a result");
+    client.notify("notifications/initialized", {});
+
+    // Baseline stats
+    const baselineStats = await callTool(client, "rlm_stats");
+    assert.ok(baselineStats, "rlm_stats should return a result");
+
+    // Inject captures mimicking OpenClaw's message_received + agent_end hooks
+    const captureEnv = {
+      ...env,
+      SAGE_SOURCE: "openclaw",
+      OPENCLAW: "1",
+    };
+
+    const prompts = [
+      {
+        prompt: "How to implement a plugin system in TypeScript?",
+        response: "Use dynamic imports, define a plugin interface, register plugins at startup.",
+      },
+      {
+        prompt: "Best practices for error handling in Node.js",
+        response:
+          "Use try-catch with async/await, create custom error classes, use error middleware.",
+      },
+      {
+        prompt: "How to write unit tests with vitest?",
+        response:
+          "Install vitest, create .test.ts files, use describe/it/expect, run with npx vitest.",
+      },
+    ];
+
+    for (const { prompt, response } of prompts) {
+      // Phase 1: capture prompt (simulates message_received hook)
+      const promptExit = await runCaptureCli(sageBin, ["capture", "hook", "prompt"], {
+        ...captureEnv,
+        PROMPT: prompt,
+        SAGE_SESSION_ID: "openclaw-e2e-session",
+        SAGE_MODEL: "gpt-4",
+        SAGE_PROVIDER: "openai",
+        SAGE_CAPTURE_ATTRIBUTES_JSON: JSON.stringify({
+          openclaw: {
+            hook: "message_received",
+            sessionId: "openclaw-e2e-session",
+            channel: "test",
+          },
+        }),
+      });
+      // Exit code check (may be non-zero if daemon socket not found, but file-based fallback works)
+      assert.ok(promptExit !== null, "prompt capture should not crash");
+
+      // Phase 2: capture response (simulates agent_end hook)
+      const responseExit = await runCaptureCli(sageBin, ["capture", "hook", "response"], {
+        ...captureEnv,
+        LAST_RESPONSE: response,
+        TOKENS_INPUT: "150",
+        TOKENS_OUTPUT: "75",
+      });
+      assert.ok(responseExit !== null, "response capture should not crash");
+    }
+
+    // Run analysis via MCP
+    const analysisResult = await callTool(client, "rlm_analyze_captures", {
+      goal: "improve developer productivity",
+    });
+    assert.ok(analysisResult, "rlm_analyze_captures should return a result");
+
+    // Check patterns
+    const patterns = await callTool(client, "rlm_list_patterns", {});
+    assert.ok(patterns, "rlm_list_patterns should return a result");
+
+    // Final stats should reflect some activity
+    const finalStats = await callTool(client, "rlm_stats");
+    assert.ok(finalStats, "final rlm_stats should return a result");
+  } finally {
+    proc.kill("SIGTERM");
+  }
+});
+
+test(
+  "OpenClaw capture with custom attributes preserves metadata",
+  { timeout: TIMEOUT },
+  async () => {
+    const tmpHome = createIsolatedHome();
+    const env = isolatedEnv(tmpHome);
+
+    const attrs = {
+      openclaw: {
+        hook: "message_received",
+        sessionId: "test-sess-123",
+        sessionKey: "key-456",
+        channel: "web",
+        senderId: "user-789",
+      },
+    };
+
+    // Run capture with rich OpenClaw attributes
+    const exitCode = await runCaptureCli(sageBin, ["capture", "hook", "prompt"], {
+      ...env,
+      SAGE_SOURCE: "openclaw",
+      OPENCLAW: "1",
+      PROMPT: "Test prompt with rich metadata",
+      SAGE_SESSION_ID: "test-sess-123",
+      SAGE_MODEL: "claude-3-opus",
+      SAGE_PROVIDER: "anthropic",
+      SAGE_WORKSPACE: "/workspace/project",
+      SAGE_CAPTURE_ATTRIBUTES_JSON: JSON.stringify(attrs),
+    });
+
+    // Should not crash (exit code may be non-zero if daemon not running, that's OK)
+    assert.ok(exitCode !== null, "capture with attributes should not crash");
+  },
+);

package/tsconfig.json

@@ -10,7 +10,8 @@
     "declaration": true,
     "outDir": "dist",
     "rootDir": "src",
-    "resolveJsonModule": true
+    "resolveJsonModule": true,
+    "types": ["node"]
   },
   "include": ["src/**/*.ts"],
   "exclude": ["node_modules", "dist"]