@sage-protocol/openclaw-sage 0.1.2 → 0.1.4

package/.github/workflows/release-please.yml

@@ -0,0 +1,18 @@
+name: release-please
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@v4
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json

package/.release-please-manifest.json

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

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# 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)
+
+
+### Features
+
+* add Sage capture hooks ([f8fab39](https://github.com/sage-protocol/openclaw-sage/commit/f8fab399860de55d1949c9358a443372f0617eb6))
+* adding ci, release please and improvements ([c32f79a](https://github.com/sage-protocol/openclaw-sage/commit/c32f79a05ee9212d4e382c9131ec684c91706add))
+* adding readme ([4aea6c9](https://github.com/sage-protocol/openclaw-sage/commit/4aea6c950e2dcf276ebcb492cfe70b6ac4cd138e))
+
+
+### Bug Fixes
+
+* fixing manifest naming ([28d6add](https://github.com/sage-protocol/openclaw-sage/commit/28d6add05e0b4e60b17993aaf73a23ef55ab1c94))
+* fixing missing openclaw manifest ([5062ae7](https://github.com/sage-protocol/openclaw-sage/commit/5062ae789d2733a209ce2f0c63453779f73245fb))
+
+## Changelog
+
+All notable changes to this package are documented here.

package/README.md

@@ -1,6 +1,13 @@
-# @sage-protocol/openclaw-sage
+# Sage Plugin (OpenClaw)
 
-Sage Protocol MCP bridge plugin for OpenClaw. Provides prompt libraries, skills, governance, and on-chain operations directly in OpenClaw sessions.
+MCP bridge plugin that exposes all Sage Protocol tools inside OpenClaw. Spawns the sage MCP server as a child process and translates JSON-RPC calls into registered OpenClaw tools.
+
+## What It Does
+
+- **MCP Tool Bridge** - Spawns `sage mcp start` and translates JSON-RPC tool calls into native OpenClaw tools
+- **Dynamic Registration** - Discovers available tools at startup and registers them with typed schemas
+- **RLM Capture** - Records prompt/response pairs for Sage's RLM feedback loop
+- **Crash Recovery** - Automatically restarts the MCP subprocess on unexpected exits
 
 ## Install
 
@@ -8,11 +15,6 @@ Sage Protocol MCP bridge plugin for OpenClaw. Provides prompt libraries, skills,
 openclaw plugins install @sage-protocol/openclaw-sage
 ```
 
-## Requirements
-
-- [Sage CLI](https://github.com/sage-protocol/sage-cli) installed and available on PATH
-- OpenClaw v0.1.0+
-
 ## Configuration
 
 The plugin auto-detects the `sage` binary from PATH. To override:
@@ -23,15 +25,44 @@ 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
 
-The plugin exposes Sage Protocol MCP tools inside OpenClaw:
+Once loaded, all Sage MCP tools are available in OpenClaw:
+
+- **Prompts & Libraries** - Search, list, create, and manage prompt libraries
+- **Skills** - Discover and activate skills from Sage Protocol, GitHub, or local sources
+- **Builder** - AI-powered prompt recommendations and synthesis
+- **Governance** - List DAOs, view proposals, check voting power
+- **Hub** - Start/stop additional MCP servers (memory, brave-search, github, etc.)
 
-- **Prompts & Libraries** — search, list, create, and manage prompt libraries
-- **Skills** — discover and activate skills from Sage Protocol, GitHub, or local sources
-- **Builder** — AI-powered prompt recommendations and synthesis
-- **Governance** — list DAOs, view proposals, check voting power
-- **Hub** — start/stop additional MCP servers (memory, brave-search, github, etc.)
+## Requirements
+
+- Sage CLI on PATH
+- OpenClaw v0.1.0+
 
 ## Development
 

package/SOUL.md

@@ -0,0 +1,64 @@
+# OpenClaw Agent SOUL
+
+This file defines the default behavior for an OpenClaw agent operating in the Sage Protocol ecosystem.
+
+## Core Objective
+
+Help the user get productive with Sage as fast as possible by reliably steering onboarding toward:
+
+```bash
+sage init
+sage agent quickstart
+```
+
+## When To Prompt For Onboarding
+
+Prompt the user to run `sage init` and/or `sage agent quickstart` when any of the following is true:
+
+- 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, SXXX tokens needed, IPFS credits missing, library sync failing).
+
+## How To Prompt (Non-Spammy)
+
+- Ask once, early, and only repeat if the user is blocked by missing setup.
+- Prefer one short message with a single actionable next step.
+- Don't derail the task: if the user is already mid-task, suggest onboarding as a quick fix only when it unblocks progress.
+
+## Recommended Message Templates
+
+If Sage is not initialized:
+
+```text
+Run `sage init` to set up the Sage skill + MCP integration for your environment.
+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
+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:
+
+```text
+Install the OpenClaw MCP bridge: `openclaw plugins install @sage-protocol/openclaw-sage`.
+Then run: `sage init` and `sage agent quickstart`.
+```
+
+## OpenClaw Skill Directory
+
+OpenClaw loads skills from:
+
+```text
+~/.openclaw/workspace/skills/
+```
+
+## Guardrails
+
+- Don't instruct `git push`, key export, or any destructive command unless the user explicitly asks.
+- Don't ask the user to paste secrets (tokens, private keys). Use `sage wallet connect -w privy` (OAuth) or documented wallet flows.
+- Prefer the unified `sage suggest ...` family for discovery, but onboarding comes first.

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.2",
+  "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",
@@ -14,11 +14,13 @@
     "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/release-please-config.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "release-type": "node",
+  "include-v-in-tag": true,
+  "bump-minor-pre-major": true,
+  "bump-patch-for-minor-pre-major": true,
+  "packages": {
+    ".": {
+      "package-name": "@sage-protocol/openclaw-sage",
+      "changelog-path": "CHANGELOG.md"
+    }
+  }
+}

package/src/index.ts

@@ -1,7 +1,37 @@
 import { Type } from "@sinclair/typebox";
+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.
  *
@@ -25,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>;
 };
 
 /**
@@ -96,65 +217,229 @@ function toToolResult(mcpResult: unknown) {
   };
 }
 
+/**
+ * Load custom server configurations from ~/.config/sage/mcp-servers.toml
+ */
+function loadCustomServers(): CustomServerConfig[] {
+  const configPath = join(homedir(), ".config", "sage", "mcp-servers.toml");
+
+  if (!existsSync(configPath)) {
+    return [];
+  }
+
+  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 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 [];
+  }
+}
+
+/**
+ * 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}`);
+  }
+}
+
 // ── Plugin Definition ────────────────────────────────────────────────────────
 
-let bridge: McpBridge | null = null;
+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"]);
+    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);
 
-    bridge.on("log", (line: string) => api.logger.info(`[sage-mcp] ${line}`));
-    bridge.on("error", (err: Error) => api.logger.error(`[sage-mcp] ${err.message}`));
+    // 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);
@@ -170,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

@@ -0,0 +1,132 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+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.
+  const binDir = resolve(new URL("..", import.meta.url).pathname, "..", "target", "debug");
+  const sep = process.platform === "win32" ? ";" : ":";
+  process.env.PATH = `${binDir}${sep}${process.env.PATH ?? ""}`;
+  return { binDir };
+}
+
+test("McpBridge can initialize, list tools, and call a native tool", async () => {
+  const sageBin = resolve(new URL("..", import.meta.url).pathname, "..", "target", "debug", "sage");
+  const bridge = new McpBridge(sageBin, ["mcp", "start"]);
+  await bridge.start();
+  try {
+    const tools = await bridge.listTools();
+    assert.ok(Array.isArray(tools));
+    assert.ok(tools.length > 0);
+
+    const hasProjectContext = tools.some((t) => t.name === "get_project_context");
+    assert.ok(hasProjectContext, "expected get_project_context tool to exist");
+
+    const result = await bridge.callTool("get_project_context", {});
+    assert.ok(result && typeof result === "object");
+  } finally {
+    await bridge.stop();
+  }
+});
+
+test("OpenClaw plugin registers MCP tools via sage mcp start", async () => {
+  addSageDebugBinToPath();
+
+  const registeredTools: string[] = [];
+  const services: Array<{ id: string; start: Function; stop?: Function }> = [];
+
+  const api = {
+    id: "t",
+    name: "t",
+    logger: {
+      info: (_: string) => {},
+      warn: (_: string) => {},
+      error: (_: string) => {},
+    },
+    registerTool: (tool: any) => {
+      if (tool?.name) registeredTools.push(tool.name);
+    },
+    registerService: (svc: any) => {
+      services.push(svc);
+    },
+    on: (_hook: string, _handler: any) => {},
+  };
+
+  plugin.register(api);
+  const svc = services.find((s) => s.id === "sage-mcp-bridge");
+  assert.ok(svc, "expected sage-mcp-bridge service to be registered");
+
+  await svc!.start({
+    config: {},
+    stateDir: "/tmp",
+    logger: api.logger,
+  });
+
+  // Tool names are prefixed with `sage_` in this plugin.
+  assert.ok(
+    registeredTools.some((n) => n.startsWith("sage_")),
+    "expected at least one sage_* tool",
+  );
+
+  if (svc!.stop) {
+    await svc!.stop({
+      config: {},
+      stateDir: "/tmp",
+      logger: api.logger,
+    });
+  }
+});
+
+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"]