@sage-protocol/openclaw-sage 0.1.5 → 0.1.6

package/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  typecheck-and-unit-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: TypeScript typecheck
+        run: npm run typecheck
+
+      - name: Run unit tests (no sage binary required)
+        run: node --import tsx src/mcp-bridge.test.ts
+        env:
+          # Unit tests that don't need the sage binary will pass;
+          # integration tests that need it will be skipped on CI
+          NODE_OPTIONS: "--test-only"

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.1.5"
+  ".": "0.1.6"
 }

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.1.6](https://github.com/sage-protocol/openclaw-sage/compare/openclaw-sage-v0.1.5...openclaw-sage-v0.1.6) (2026-02-05)
+
+
+### Features
+
+* P0-P2 fixes — version sync, schema conversion, env passthrough, status tool, error enrichment ([5e2d6f4](https://github.com/sage-protocol/openclaw-sage/commit/5e2d6f4ab468d53cf9bf36d504cde1b32ed801f3))
+
 ## [0.1.5](https://github.com/sage-protocol/openclaw-sage/compare/openclaw-sage-v0.1.4...openclaw-sage-v0.1.5) (2026-02-04)
 
 

package/README.md

@@ -5,9 +5,12 @@ MCP bridge plugin that exposes all Sage Protocol tools inside OpenClaw. Spawns t
 ## 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
+- **Dynamic Registration** - Discovers 60+ tools at startup and registers them with typed schemas
+- **Auto-Context Injection** - Injects Sage tool context and skill suggestions at agent start
+- **Error Context** - Enriches error messages with actionable hints (wallet, auth, network, credits)
+- **Injection Guard** - Optional prompt-injection scanning for fetched prompt content
 - **Crash Recovery** - Automatically restarts the MCP subprocess on unexpected exits
+- **External Servers** - Loads additional MCP servers from `~/.config/sage/mcp-servers.toml`
 
 ## Install
 
@@ -21,10 +24,13 @@ The plugin auto-detects the `sage` binary from PATH. To override:
 
 ```json
 {
-  "sageBinary": "/path/to/sage"
+  "sageBinary": "/path/to/sage",
+  "sageProfile": "testnet"
 }
 ```
 
+The `sageProfile` field maps to `SAGE_PROFILE` and controls which network/wallet the CLI uses. The plugin also passes through these env vars when set: `SAGE_PROFILE`, `SAGE_PAY_TO_PIN`, `SAGE_IPFS_WORKER_URL`, `SAGE_API_URL`, `KEYSTORE_PASSWORD`.
+
 ### 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`).
@@ -73,17 +79,60 @@ The internal hook exists mainly for bootstrap-file injection; the plugin is the
 
 ## What It Provides
 
-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.)
+Once loaded, all Sage MCP tools are available in OpenClaw with a `sage_` prefix:
+
+### Prompts & Libraries
+- `sage_search_prompts` - Hybrid keyword + semantic search
+- `sage_list_prompts` - Browse prompts by source
+- `sage_get_prompt` - Full prompt content
+- `sage_quick_create_prompt` - Create new prompts
+- `sage_list_libraries` - Local/on-chain libraries
+
+### Skills
+- `sage_search_skills` / `sage_list_skills` - Find skills
+- `sage_get_skill` - Skill details and content
+- `sage_use_skill` - Activate a skill (auto-provisions MCP servers)
+- `sage_sync_skills` - Sync from daemon
+
+### Builder
+- `sage_builder_recommend` - AI-powered prompt suggestions
+- `sage_builder_synthesize` - Synthesize from intent
+- `sage_builder_vote` - Feedback on recommendations
+
+### Governance & DAOs
+- `sage_list_subdaos` - List available DAOs
+- `sage_list_proposals` / `sage_list_governance_proposals` - View proposals
+- `sage_list_governance_votes` - Vote breakdown
+- `sage_get_voting_power` - Voting power with NFT multipliers
+
+### Tips, Bounties & Marketplace
+- `sage_list_tips` / `sage_list_tip_stats` - Tips activity and stats
+- `sage_list_bounties` - Open/completed bounties
+- `sage_list_bounty_library_additions` - Pending library merges
+
+### Chat & Social
+- `sage_chat_list_rooms` / `sage_chat_send` / `sage_chat_history` - Real-time messaging
+
+### RLM (Recursive Language Model)
+- `sage_rlm_stats` - Statistics and capture counts
+- `sage_rlm_analyze_captures` - Analyze captured data
+- `sage_rlm_list_patterns` - Discovered patterns
+
+### Memory & Knowledge Graph
+- `sage_memory_create_entities` / `sage_memory_search_nodes` / `sage_memory_read_graph`
+
+### Hub (External MCP Servers)
+- `sage_hub_list_servers` - List available MCP servers
+- `sage_hub_start_server` - Start a server
+- `sage_hub_stop_server` - Stop a server
+- `sage_hub_status` - Check running servers
+
+### Plugin Meta
+- `sage_status` - Bridge health, wallet, network, tool count
 
 ## Requirements
 
-- Sage CLI on PATH
+- Sage CLI on PATH (v0.9.16+)
 - OpenClaw v0.1.0+
 
 ## Development

package/openclaw.plugin.json

@@ -5,6 +5,11 @@
       "label": "Sage Binary Path",
       "placeholder": "sage",
       "help": "Path to sage CLI binary (auto-detected from PATH if empty)"
+    },
+    "sageProfile": {
+      "label": "Sage Profile",
+      "placeholder": "default",
+      "help": "Sage CLI profile name (e.g. testnet, mainnet). Maps to SAGE_PROFILE env var."
     }
   },
   "configSchema": {
@@ -15,6 +20,10 @@
         "type": "string",
         "description": "Path to sage binary (default: auto-detect from PATH)"
       },
+      "sageProfile": {
+        "type": "string",
+        "description": "Sage CLI profile name to use (default: from SAGE_PROFILE env or 'default')"
+      },
       "autoInjectContext": {
         "type": "boolean",
         "description": "Inject Sage tool context into the agent at start (default: true)"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sage-protocol/openclaw-sage",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Sage MCP bridge plugin for OpenClaw — prompt libraries, skills, governance, and on-chain operations",
   "main": "src/index.ts",
   "type": "module",

package/src/index.ts

@@ -1,32 +1,72 @@
-import { Type } from "@sinclair/typebox";
+import { Type, type TSchema } from "@sinclair/typebox";
 import { readFileSync, existsSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { join, resolve, dirname } from "node:path";
 import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
 import TOML from "@iarna/toml";
 
 import { McpBridge, type McpToolDef } from "./mcp-bridge.js";
 
+// Read version from package.json at module load time
+const __dirname_compat = dirname(fileURLToPath(import.meta.url));
+const PKG_VERSION: string = (() => {
+  try {
+    const pkg = JSON.parse(readFileSync(resolve(__dirname_compat, "..", "package.json"), "utf8"));
+    return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+})();
+
 const SAGE_CONTEXT = `## Sage MCP Tools Available
 
-You have access to Sage MCP tools for prompts, skills, and knowledge discovery.
+You have access to Sage MCP tools for prompts, skills, governance, and on-chain operations.
 
 ### 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
+- \`builder_synthesize\` - Create new prompts from a description
 
 ### 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)
+- \`sync_skills\` - Sync skills from daemon
+
+### Governance & DAOs
+- \`list_subdaos\` - List available DAOs
+- \`list_proposals\` / \`sage_list_governance_proposals\` - View proposals
+- \`sage_list_governance_votes\` - View vote breakdown
+- \`get_voting_power\` - Check voting power with NFT multipliers
+
+### Tips, Bounties & Marketplace
+- \`sage_list_tips\` / \`sage_list_tip_stats\` - Tips activity and stats
+- \`sage_list_bounties\` - Open/completed bounties
+- \`sage_list_bounty_library_additions\` - Pending library merges
+
+### Chat & Social
+- \`chat_list_rooms\` / \`chat_send\` / \`chat_history\` - Real-time messaging
+- Social follow/unfollow (via CLI)
+
+### RLM (Recursive Language Model)
+- \`rlm_stats\` - RLM statistics and capture counts
+- \`rlm_analyze_captures\` - Analyze captured prompt/response pairs
+- \`rlm_list_patterns\` - Show discovered patterns
+
+### Memory & Knowledge Graph
+- \`memory_create_entities\` / \`memory_search_nodes\` / \`memory_read_graph\` - Knowledge graph ops
 
 ### 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
 
+### Plugin Status
+- \`sage_status\` - Check bridge health, connected network, wallet, and tool count
+
 ### 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
@@ -185,6 +225,58 @@ type CustomServerConfig = {
   env?: Record<string, string>;
 };
 
+/**
+ * Convert a single MCP JSON Schema property into a TypeBox type.
+ * Handles nested objects, typed arrays, and enums.
+ */
+function jsonSchemaToTypebox(prop: Record<string, unknown>): TSchema {
+  const desc = typeof prop.description === "string" ? prop.description : undefined;
+  const opts: Record<string, unknown> = {};
+  if (desc) opts.description = desc;
+
+  // Enum support: string enums become Type.Union of Type.Literal
+  if (Array.isArray(prop.enum) && prop.enum.length > 0) {
+    const literals = prop.enum
+      .filter((v): v is string | number | boolean => ["string", "number", "boolean"].includes(typeof v))
+      .map((v) => Type.Literal(v));
+    if (literals.length > 0) {
+      return literals.length === 1 ? literals[0] : Type.Union(literals, opts);
+    }
+  }
+
+  switch (prop.type) {
+    case "number":
+    case "integer":
+      return Type.Number(opts);
+    case "boolean":
+      return Type.Boolean(opts);
+    case "array": {
+      // Typed array items
+      const items = prop.items as Record<string, unknown> | undefined;
+      const itemType = items && typeof items === "object" ? jsonSchemaToTypebox(items) : Type.Unknown();
+      return Type.Array(itemType, opts);
+    }
+    case "object": {
+      // Nested object with known properties
+      const nested = prop.properties as Record<string, Record<string, unknown>> | undefined;
+      if (nested && typeof nested === "object" && Object.keys(nested).length > 0) {
+        const nestedRequired = new Set(
+          Array.isArray(prop.required) ? (prop.required as string[]) : [],
+        );
+        const nestedFields: Record<string, TSchema> = {};
+        for (const [k, v] of Object.entries(nested)) {
+          const field = jsonSchemaToTypebox(v);
+          nestedFields[k] = nestedRequired.has(k) ? field : Type.Optional(field);
+        }
+        return Type.Object(nestedFields, { ...opts, additionalProperties: true });
+      }
+      return Type.Record(Type.String(), Type.Unknown(), opts);
+    }
+    default:
+      return Type.String(opts);
+  }
+}
+
 /**
  * Convert an MCP JSON Schema inputSchema into a TypeBox object schema
  * that OpenClaw's tool system accepts.
@@ -199,35 +291,14 @@ function mcpSchemaToTypebox(inputSchema?: Record<string, unknown>) {
     Array.isArray(inputSchema.required) ? (inputSchema.required as string[]) : [],
   );
 
-  const fields: Record<string, unknown> = {};
+  const fields: Record<string, TSchema> = {};
 
   for (const [key, prop] of Object.entries(properties)) {
-    const desc = typeof prop.description === "string" ? prop.description : undefined;
-    const opts = desc ? { description: desc } : {};
-
-    let field: unknown;
-    switch (prop.type) {
-      case "number":
-      case "integer":
-        field = Type.Number(opts);
-        break;
-      case "boolean":
-        field = Type.Boolean(opts);
-        break;
-      case "array":
-        field = Type.Array(Type.Unknown(), opts);
-        break;
-      case "object":
-        field = Type.Record(Type.String(), Type.Unknown(), opts);
-        break;
-      default:
-        field = Type.String(opts);
-    }
-
-    fields[key] = required.has(key) ? field : Type.Optional(field as any);
+    const field = jsonSchemaToTypebox(prop);
+    fields[key] = required.has(key) ? field : Type.Optional(field);
   }
 
-  return Type.Object(fields as any, { additionalProperties: true });
+  return Type.Object(fields, { additionalProperties: true });
 }
 
 function toToolResult(mcpResult: unknown) {
@@ -329,7 +400,7 @@ const externalBridges: Map<string, McpBridge> = new Map();
 const plugin = {
   id: "openclaw-sage",
   name: "Sage Protocol",
-  version: "0.2.0",
+  version: PKG_VERSION,
   description:
     "Sage MCP tools for prompt libraries, skills, governance, and on-chain operations (including external servers)",
 
@@ -338,6 +409,9 @@ const plugin = {
     const sageBinary = typeof pluginCfg.sageBinary === "string" && pluginCfg.sageBinary.trim()
       ? pluginCfg.sageBinary.trim()
       : "sage";
+    const sageProfile = typeof pluginCfg.sageProfile === "string" && pluginCfg.sageProfile.trim()
+      ? pluginCfg.sageProfile.trim()
+      : undefined;
 
     const autoInject = pluginCfg.autoInjectContext !== false;
     const autoSuggest = pluginCfg.autoSuggestSkills !== false;
@@ -395,13 +469,29 @@ const plugin = {
       }
     };
 
-    // Main sage MCP bridge - pass HOME to ensure auth state is found
-    sageBridge = new McpBridge(sageBinary, ["mcp", "start"], {
+    // Build env for sage subprocess — pass through auth/wallet state and profile config
+    const sageEnv: Record<string, string> = {
       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"),
+    };
+    // Pass through Sage-specific env vars when set
+    const passthroughVars = [
+      "SAGE_PROFILE", "SAGE_PAY_TO_PIN", "SAGE_IPFS_WORKER_URL",
+      "SAGE_IPFS_UPLOAD_TOKEN", "SAGE_API_URL", "SAGE_HOME",
+      "KEYSTORE_PASSWORD", "SAGE_PROMPT_GUARD_API_KEY",
+    ];
+    for (const key of passthroughVars) {
+      if (process.env[key]) sageEnv[key] = process.env[key]!;
+    }
+    // Config-level profile override takes precedence
+    if (sageProfile) sageEnv.SAGE_PROFILE = sageProfile;
+
+    // Main sage MCP bridge
+    sageBridge = new McpBridge(sageBinary, ["mcp", "start"], sageEnv, {
+      clientVersion: PKG_VERSION,
     });
     sageBridge.on("log", (line: string) => api.logger.info(`[sage-mcp] ${line}`));
     sageBridge.on("error", (err: Error) => api.logger.error(`[sage-mcp] ${err.message}`));
@@ -426,6 +516,9 @@ const plugin = {
               scanText,
             });
           }
+
+          // Register sage_status meta-tool for bridge health reporting
+          registerStatusTool(api, tools.length);
         } catch (err) {
           ctx.logger.error(
             `Failed to start sage MCP bridge: ${err instanceof Error ? err.message : String(err)}`,
@@ -535,6 +628,81 @@ const plugin = {
   },
 };
 
+/** Map common error patterns to actionable hints */
+function enrichErrorMessage(err: Error, toolName: string): string {
+  const msg = err.message;
+
+  // Wallet not configured
+  if (/wallet|signer|no.*account|not.*connected/i.test(msg)) {
+    return `${msg}\n\nHint: Run \`sage wallet connect\` to configure a wallet, or set KEYSTORE_PASSWORD for automated flows.`;
+  }
+  // Auth / token issues
+  if (/auth|unauthorized|403|401|token.*expired|challenge/i.test(msg)) {
+    return `${msg}\n\nHint: Run \`sage ipfs setup\` to refresh authentication, or check SAGE_IPFS_UPLOAD_TOKEN.`;
+  }
+  // Network / RPC failures
+  if (/rpc|network|timeout|ECONNREFUSED|ENOTFOUND|fetch.*failed/i.test(msg)) {
+    return `${msg}\n\nHint: Check your network connection. Set SAGE_PROFILE to switch between testnet/mainnet.`;
+  }
+  // MCP bridge not running
+  if (/not running|not initialized|bridge stopped/i.test(msg)) {
+    return `${msg}\n\nHint: The Sage MCP bridge may have crashed. Try restarting the plugin or running \`sage mcp start\` to verify the CLI works.`;
+  }
+  // Credits
+  if (/credits|insufficient.*balance|IPFS.*balance/i.test(msg)) {
+    return `${msg}\n\nHint: Run \`sage ipfs faucet\` (testnet) or purchase credits via \`sage wallet buy\`.`;
+  }
+
+  return msg;
+}
+
+function registerStatusTool(api: PluginApi, sageToolCount: number) {
+  api.registerTool(
+    {
+      name: "sage_status",
+      label: "Sage: status",
+      description: "Check Sage plugin health: bridge connection, tool count, network profile, and wallet status",
+      parameters: Type.Object({}),
+      execute: async () => {
+        const bridgeReady = sageBridge?.isReady() ?? false;
+        const externalCount = externalBridges.size;
+        const externalIds = Array.from(externalBridges.keys());
+
+        // Try to get wallet + network info from sage
+        let walletInfo = "unknown";
+        let networkInfo = "unknown";
+        if (bridgeReady && sageBridge) {
+          try {
+            const ctx = await sageBridge.callTool("get_project_context", {});
+            const json = extractJsonFromMcpResult(ctx) as any;
+            if (json?.wallet?.address) walletInfo = json.wallet.address;
+            if (json?.network) networkInfo = json.network;
+          } catch {
+            // Not critical — report what we can
+          }
+        }
+
+        const status = {
+          pluginVersion: PKG_VERSION,
+          bridgeConnected: bridgeReady,
+          sageToolCount,
+          externalServerCount: externalCount,
+          externalServers: externalIds,
+          wallet: walletInfo,
+          network: networkInfo,
+          profile: process.env.SAGE_PROFILE || "default",
+        };
+
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify(status, null, 2) }],
+          details: status,
+        };
+      },
+    },
+    { name: "sage_status", optional: true },
+  );
+}
+
 function registerMcpTool(
   api: PluginApi,
   prefix: string,
@@ -549,13 +717,26 @@ function registerMcpTool(
   const name = `${prefix}_${tool.name}`;
   const schema = mcpSchemaToTypebox(tool.inputSchema);
 
+  // Extract category from tool annotations if available
+  const category = typeof tool.annotations?.category === "string"
+    ? tool.annotations.category
+    : undefined;
+  const label = category
+    ? `${prefix}: ${category} / ${tool.name}`
+    : `${prefix}: ${tool.name}`;
+
   api.registerTool(
     {
       name,
-      label: `${prefix}: ${tool.name}`,
+      label,
       description: tool.description ?? `MCP tool: ${prefix}/${tool.name}`,
       parameters: schema,
       execute: async (_toolCallId: string, params: Record<string, unknown>) => {
+        if (!bridge.isReady()) {
+          return toToolResult({
+            error: "MCP bridge not connected. The sage subprocess may have crashed — try restarting the plugin.",
+          });
+        }
         try {
           const result = await bridge.callTool(tool.name, params);
 
@@ -595,9 +776,11 @@ function registerMcpTool(
 
           return toToolResult(result);
         } catch (err) {
-          return toToolResult({
-            error: err instanceof Error ? err.message : String(err),
-          });
+          const enriched = enrichErrorMessage(
+            err instanceof Error ? err : new Error(String(err)),
+            tool.name,
+          );
+          return toToolResult({ error: enriched });
         }
       },
     },
@@ -608,8 +791,12 @@ function registerMcpTool(
 export default plugin;
 
 export const __test = {
+  PKG_VERSION,
   SAGE_CONTEXT,
   normalizePrompt,
   extractJsonFromMcpResult,
   formatSkillSuggestions,
+  mcpSchemaToTypebox,
+  jsonSchemaToTypebox,
+  enrichErrorMessage,
 };

package/src/mcp-bridge.test.ts

@@ -1,6 +1,7 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 import { resolve } from "node:path";
+import { readFileSync } from "node:fs";
 
 import { McpBridge } from "./mcp-bridge.js";
 import plugin from "./index.js";
@@ -14,11 +15,153 @@ function addSageDebugBinToPath() {
   return { binDir };
 }
 
+// ── P0: Version consistency ──────────────────────────────────────────
+
+test("PKG_VERSION matches package.json version", () => {
+  const pkgPath = resolve(new URL("..", import.meta.url).pathname, "package.json");
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  assert.equal(__test.PKG_VERSION, pkg.version, "PKG_VERSION should match package.json");
+});
+
+test("plugin.version matches package.json version", () => {
+  const pkgPath = resolve(new URL("..", import.meta.url).pathname, "package.json");
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  assert.equal(plugin.version, pkg.version, "plugin.version should match package.json");
+});
+
+// ── P1: Schema conversion ────────────────────────────────────────────
+
+test("mcpSchemaToTypebox handles string properties", () => {
+  const schema = __test.mcpSchemaToTypebox({
+    type: "object",
+    properties: {
+      name: { type: "string", description: "A name" },
+    },
+    required: ["name"],
+  }) as any;
+  assert.ok(schema);
+  assert.equal(schema.type, "object");
+  assert.ok(schema.properties.name, "should have name property");
+});
+
+test("mcpSchemaToTypebox handles enum properties", () => {
+  const schema = __test.mcpSchemaToTypebox({
+    type: "object",
+    properties: {
+      vote: { type: "string", enum: ["for", "against", "abstain"], description: "Vote direction" },
+    },
+    required: ["vote"],
+  }) as any;
+  assert.ok(schema);
+  const voteField = schema.properties.vote;
+  assert.ok(voteField, "should have vote property");
+  // Union of literals produces anyOf
+  assert.ok(voteField.anyOf || voteField.const || voteField.enum,
+    "enum should produce union of literals or single literal");
+});
+
+test("mcpSchemaToTypebox handles typed arrays", () => {
+  const schema = __test.mcpSchemaToTypebox({
+    type: "object",
+    properties: {
+      tags: { type: "array", items: { type: "string" }, description: "Tags list" },
+    },
+  }) as any;
+  assert.ok(schema);
+  const tagsField = schema.properties.tags;
+  assert.ok(tagsField, "should have tags property");
+});
+
+test("mcpSchemaToTypebox handles nested objects", () => {
+  const schema = __test.mcpSchemaToTypebox({
+    type: "object",
+    properties: {
+      config: {
+        type: "object",
+        properties: {
+          timeout: { type: "number", description: "Timeout in ms" },
+          retry: { type: "boolean" },
+        },
+        required: ["timeout"],
+      },
+    },
+  }) as any;
+  assert.ok(schema);
+  const configField = schema.properties.config;
+  assert.ok(configField, "should have config property");
+  assert.ok(configField.properties?.timeout, "nested object should have timeout");
+});
+
+test("mcpSchemaToTypebox handles empty/missing schema gracefully", () => {
+  assert.ok(__test.mcpSchemaToTypebox(undefined));
+  assert.ok(__test.mcpSchemaToTypebox({}));
+  assert.ok(__test.mcpSchemaToTypebox({ type: "object" }));
+});
+
+test("jsonSchemaToTypebox handles single enum value as literal", () => {
+  const result = __test.jsonSchemaToTypebox({ type: "string", enum: ["only_value"] });
+  assert.ok(result);
+  assert.equal(result.const, "only_value");
+});
+
+// ── P2: Error enrichment ─────────────────────────────────────────────
+
+test("enrichErrorMessage adds wallet hint for wallet errors", () => {
+  const err = new Error("No wallet connected");
+  const enriched = __test.enrichErrorMessage(err, "list_proposals");
+  assert.ok(enriched.includes("sage wallet connect"), "should suggest wallet connect");
+});
+
+test("enrichErrorMessage adds auth hint for auth errors", () => {
+  const err = new Error("401 Unauthorized: token expired");
+  const enriched = __test.enrichErrorMessage(err, "ipfs_upload");
+  assert.ok(enriched.includes("sage ipfs setup"), "should suggest ipfs setup");
+});
+
+test("enrichErrorMessage adds network hint for RPC errors", () => {
+  const err = new Error("ECONNREFUSED 127.0.0.1:8545");
+  const enriched = __test.enrichErrorMessage(err, "list_subdaos");
+  assert.ok(enriched.includes("SAGE_PROFILE"), "should mention SAGE_PROFILE");
+});
+
+test("enrichErrorMessage adds bridge hint for bridge errors", () => {
+  const err = new Error("MCP bridge not running");
+  const enriched = __test.enrichErrorMessage(err, "search_prompts");
+  assert.ok(enriched.includes("sage mcp start"), "should suggest mcp start");
+});
+
+test("enrichErrorMessage adds credits hint for balance errors", () => {
+  const err = new Error("Insufficient IPFS balance");
+  const enriched = __test.enrichErrorMessage(err, "ipfs_pin");
+  assert.ok(enriched.includes("sage ipfs faucet"), "should suggest faucet");
+});
+
+test("enrichErrorMessage passes through unknown errors", () => {
+  const err = new Error("Something unexpected");
+  const enriched = __test.enrichErrorMessage(err, "unknown_tool");
+  assert.equal(enriched, "Something unexpected");
+});
+
+// ── P2: SAGE_CONTEXT completeness ────────────────────────────────────
+
+test("SAGE_CONTEXT includes all major tool categories", () => {
+  const ctx = __test.SAGE_CONTEXT;
+  assert.ok(ctx.includes("Governance & DAOs"), "should include Governance");
+  assert.ok(ctx.includes("Tips, Bounties"), "should include Tips/Bounties");
+  assert.ok(ctx.includes("Chat & Social"), "should include Chat");
+  assert.ok(ctx.includes("RLM"), "should include RLM");
+  assert.ok(ctx.includes("Memory"), "should include Memory");
+  assert.ok(ctx.includes("sage_status"), "should include status tool");
+});
+
+// ── Existing tests (integration — require sage binary) ───────────────
+
 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 {
+    assert.ok(bridge.isReady(), "bridge should be ready after start");
     const tools = await bridge.listTools();
     assert.ok(Array.isArray(tools));
     assert.ok(tools.length > 0);
@@ -30,6 +173,7 @@ test("McpBridge can initialize, list tools, and call a native tool", async () =>
     assert.ok(result && typeof result === "object");
   } finally {
     await bridge.stop();
+    assert.ok(!bridge.isReady(), "bridge should not be ready after stop");
   }
 });
 
@@ -72,6 +216,12 @@ test("OpenClaw plugin registers MCP tools via sage mcp start", async () => {
     "expected at least one sage_* tool",
   );
 
+  // sage_status meta-tool should be registered
+  assert.ok(
+    registeredTools.includes("sage_status"),
+    "expected sage_status meta-tool to be registered",
+  );
+
   if (svc!.stop) {
     await svc!.stop({
       config: {},

package/src/mcp-bridge.ts

@@ -8,6 +8,8 @@ export type McpToolDef = {
   name: string;
   description?: string;
   inputSchema?: Record<string, unknown>;
+  /** Tool category (from Sage MCP registry) */
+  annotations?: Record<string, unknown>;
 };
 
 /** JSON-RPC request/response types */
@@ -42,12 +44,21 @@ export class McpBridge extends EventEmitter {
   private retries = 0;
   private stopped = false;
 
+  private clientVersion: string;
+
   constructor(
     private command: string,
     private args: string[],
     private env?: Record<string, string>,
+    opts?: { clientVersion?: string },
   ) {
     super();
+    this.clientVersion = opts?.clientVersion ?? "0.0.0";
+  }
+
+  /** Whether the bridge is connected and ready for requests */
+  isReady(): boolean {
+    return this.ready && this.proc !== null && !this.stopped;
   }
 
   async start(): Promise<void> {
@@ -133,7 +144,7 @@ export class McpBridge extends EventEmitter {
     const result = (await this.request("initialize", {
       protocolVersion: "2024-11-05",
       capabilities: {},
-      clientInfo: { name: "openclaw-sage-plugin", version: "0.1.0" },
+      clientInfo: { name: "openclaw-sage-plugin", version: this.clientVersion },
     })) as { serverInfo?: { name?: string } };
 
     this.notify("notifications/initialized", {});