@sage-protocol/openclaw-sage 0.1.2 → 0.1.3

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.3"
+}

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## [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:
@@ -25,13 +27,18 @@ The plugin auto-detects the `sage` binary from PATH. To override:
 
 ## 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,62 @@
+# 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, faucet 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.
+After that, run `sage agent quickstart` to claim testnet tokens + IPFS credits.
+```
+
+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).
+```
+
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sage-protocol/openclaw-sage",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Sage MCP bridge plugin for OpenClaw — prompt libraries, skills, governance, and on-chain operations",
   "main": "src/index.ts",
   "type": "module",
@@ -11,7 +11,7 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "node --import tsx src/mcp-bridge.test.ts"
+    "test": "npx --yes tsx src/mcp-bridge.test.ts"
   },
   "dependencies": {
     "@sinclair/typebox": "^0.34.0"

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,5 +1,7 @@
 import { Type } from "@sinclair/typebox";
 
+import { spawn } from "node:child_process";
+
 import { McpBridge, type McpToolDef } from "./mcp-bridge.js";
 
 /**
@@ -100,6 +102,88 @@ function toToolResult(mcpResult: unknown) {
 
 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();
+  }
+
+  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();
+  }
+
+  // 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();
+      }
+    }
+  }
+
+  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;
+  }
+
+  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;
+      }
+    }
+  }
+
+  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 "";
+}
+
+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
+  }
+}
+
 const plugin = {
   id: "openclaw-sage",
   name: "Sage Protocol",
@@ -113,6 +197,64 @@ const plugin = {
     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,
+      });
+    });
+
     api.registerService({
       id: "sage-mcp-bridge",
       start: async (ctx) => {

package/src/mcp-bridge.test.ts

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