@sage-protocol/openclaw-sage 0.1.5 → 0.1.8

package/src/index.ts

@@ -1,37 +1,49 @@
-import { Type } from "@sinclair/typebox";
-import { readFileSync, existsSync } from "node:fs";
+import { Type, type TSchema } from "@sinclair/typebox";
+import { readFileSync, existsSync, readdirSync } from "node:fs";
+import { spawn } from "node:child_process";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { join, resolve, dirname } from "node:path";
 import { createHash } from "node:crypto";
-import TOML from "@iarna/toml";
+import { fileURLToPath } from "node:url";
 
-import { McpBridge, type McpToolDef } from "./mcp-bridge.js";
+import { McpBridge } from "./mcp-bridge.js";
 
-const SAGE_CONTEXT = `## Sage MCP Tools Available
+// 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 (Code Mode)
 
-You have access to Sage MCP tools for prompts, skills, and knowledge discovery.
+You have access to Sage through a consolidated Code Mode interface.
+Sage internal domains are available immediately through Code Mode.
+Only external MCP servers need lifecycle management outside Code Mode: start/stop them with Sage CLI,
+the Sage app, or raw MCP \`hub_*\` tools, then use \`domain: "external"\` here.
 
-### 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
+### Core Tools
+- \`sage_search\` — Read-only search across Sage domains. Params: \`{domain, action, params}\`
+- \`sage_execute\` — Mutations across Sage domains. Same params.
 
-### 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)
+Domains: prompts, skills, builder, governance, chat, social, rlm, library_sync, security, meta, help, external
 
-### 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
+Examples:
+- Discover actions: sage_search { domain: "help", action: "list", params: {} }
+- Search prompts: sage_search { domain: "prompts", action: "search", params: { query: "..." } }
+- Use a skill: sage_execute { domain: "skills", action: "use", params: { key: "..." } }
+- Project context: sage_search { domain: "meta", action: "get_project_context", params: {} }
+- Inspect running external servers: sage_search { domain: "external", action: "list_servers" }
+- Call an external tool (auto-route): sage_execute { domain: "external", action: "call", params: { tool_name: "<tool>", tool_params: {...} } }
+- Execute an external tool (explicit): sage_execute { domain: "external", action: "execute", params: { server_id: "<id>", tool_name: "<tool>", tool_params: {...} } }`;
 
-### 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`;
+const SAGE_STATUS_CONTEXT = `\n\nPlugin meta-tool:\n- \`sage_status\` - show bridge health + wallet/network context`;
+
+const SAGE_FULL_CONTEXT = `${SAGE_CONTEXT}${SAGE_STATUS_CONTEXT}`;
 
 /**
  * Minimal type stubs for OpenClaw plugin API.
@@ -119,7 +131,11 @@ function sha256Hex(s: string): string {
 
 type SecurityScanResult = {
   shouldBlock?: boolean;
-  report?: { level?: string; issue_count?: number; issues?: Array<{ rule_id?: string; category?: string; severity?: string }> };
+  report?: {
+    level?: string;
+    issue_count?: number;
+    issues?: Array<{ rule_id?: string; category?: string; severity?: string }>;
+  };
   promptGuard?: { finding?: { detected?: boolean; type?: string; confidence?: number } };
 };
 
@@ -163,28 +179,279 @@ function formatSkillSuggestions(results: SkillSearchResult[], limit: number): st
   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}`);
+    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(
+      `- \`sage_execute\` { "domain": "skills", "action": "use", "params": { "key": "${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>;
+function isHeartbeatPrompt(prompt: string): boolean {
+  return (
+    prompt.includes("Sage Protocol Heartbeat") ||
+    prompt.includes("HEARTBEAT_OK") ||
+    prompt.includes("Heartbeat Checklist")
+  );
+}
+
+const heartbeatSuggestState = {
+  lastFullAnalysisTs: 0,
+  lastSuggestions: "",
+};
+
+async function gatherHeartbeatContext(
+  bridge: McpBridge,
+  logger: PluginLogger,
+  maxChars: number,
+): Promise<string> {
+  const parts: string[] = [];
+
+  // 1) Query RLM patterns
+  try {
+    const raw = await bridge.callTool("sage_search", {
+      domain: "rlm",
+      action: "list_patterns",
+      params: {},
+    });
+    const json = extractJsonFromMcpResult(raw);
+    if (json) parts.push(`RLM patterns: ${JSON.stringify(json)}`);
+  } catch (err) {
+    logger.warn(
+      `[heartbeat-context] RLM query failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+
+  // 2) Read recent daily notes (last 2 days)
+  try {
+    const memoryDir = join(homedir(), ".openclaw", "memory");
+    if (existsSync(memoryDir)) {
+      const now = new Date();
+      const twoDaysAgo = new Date(now.getTime() - 2 * 24 * 60 * 60_000);
+      const files = readdirSync(memoryDir)
+        .filter((f) => /^\d{4}-.*\.md$/.test(f))
+        .sort()
+        .reverse();
+
+      for (const file of files.slice(0, 4)) {
+        const dateMatch = file.match(/^(\d{4}-\d{2}-\d{2})/);
+        if (dateMatch) {
+          const fileDate = new Date(dateMatch[1]);
+          if (fileDate < twoDaysAgo) continue;
+        }
+        const content = readFileSync(join(memoryDir, file), "utf8").trim();
+        if (content) parts.push(`--- ${file} ---\n${content}`);
+      }
+    }
+  } catch (err) {
+    logger.warn(
+      `[heartbeat-context] memory read failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+
+  const combined = parts.join("\n\n");
+  return combined.length > maxChars ? combined.slice(0, maxChars) : combined;
+}
+
+async function searchSkillsForContext(
+  bridge: McpBridge,
+  context: string,
+  suggestLimit: number,
+  logger: PluginLogger,
+): Promise<string> {
+  const results: SkillSearchResult[] = [];
+
+  // Search skills against the context
+  try {
+    const raw = await bridge.callTool("sage_search", {
+      domain: "skills",
+      action: "search",
+      params: {
+        query: context,
+        source: "all",
+        limit: Math.max(20, suggestLimit),
+      },
+    });
+    const json = extractJsonFromMcpResult(raw) as any;
+    if (Array.isArray(json?.results)) results.push(...json.results);
+  } catch (err) {
+    logger.warn(
+      `[heartbeat-context] skill search failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+
+  // Also try builder recommendations
+  try {
+    const raw = await bridge.callTool("sage_search", {
+      domain: "builder",
+      action: "recommend",
+      params: { query: context },
+    });
+    const json = extractJsonFromMcpResult(raw) as any;
+    if (Array.isArray(json?.results)) {
+      for (const r of json.results) {
+        if (r?.key && !results.some((e) => e.key === r.key)) results.push(r);
+      }
+    }
+  } catch {
+    // Builder recommend is optional.
+  }
+
+  const formatted = formatSkillSuggestions(results, suggestLimit);
+  return formatted ? `## Context-Aware Skill Suggestions\n\n${formatted}` : "";
+}
+
+function pickFirstString(...values: unknown[]): string {
+  for (const value of values) {
+    if (typeof value === "string" && value.trim()) return value.trim();
+  }
+  return "";
+}
+
+function extractEventPrompt(event: any): string {
+  return pickFirstString(
+    event?.prompt,
+    event?.input,
+    event?.message?.content,
+    event?.message?.text,
+    event?.text,
+  );
+}
+
+function extractEventResponse(event: any): string {
+  const responseObj =
+    typeof event?.response === "object" && event?.response ? event.response : undefined;
+  const outputObj = typeof event?.output === "object" && event?.output ? event.output : undefined;
+  return pickFirstString(
+    event?.response,
+    responseObj?.content,
+    responseObj?.text,
+    responseObj?.message,
+    event?.output,
+    outputObj?.content,
+    outputObj?.text,
+  );
+}
+
+function extractEventSessionId(event: any): string {
+  return pickFirstString(event?.sessionId, event?.sessionID, event?.conversationId);
+}
+
+function extractEventModel(event: any): string {
+  const modelObj = typeof event?.model === "object" && event?.model ? event.model : undefined;
+  return pickFirstString(
+    event?.modelId,
+    modelObj?.modelID,
+    modelObj?.modelId,
+    modelObj?.id,
+    typeof event?.model === "string" ? event.model : "",
+  );
+}
+
+function extractEventProvider(event: any): string {
+  const modelObj = typeof event?.model === "object" && event?.model ? event.model : undefined;
+  return pickFirstString(
+    event?.provider,
+    event?.providerId,
+    modelObj?.providerID,
+    modelObj?.providerId,
+  );
+}
+
+function extractEventTokenCount(event: any, phase: "input" | "output"): string {
+  const value =
+    event?.tokens?.[phase] ??
+    event?.usage?.[`${phase}_tokens`] ??
+    event?.usage?.[phase] ??
+    event?.metrics?.[`${phase}Tokens`];
+  if (value == null) return "";
+  return String(value);
+}
+
+const SageDomain = Type.Union(
+  [
+    Type.Literal("prompts"),
+    Type.Literal("skills"),
+    Type.Literal("builder"),
+    Type.Literal("governance"),
+    Type.Literal("chat"),
+    Type.Literal("social"),
+    Type.Literal("rlm"),
+    Type.Literal("library_sync"),
+    Type.Literal("security"),
+    Type.Literal("meta"),
+    Type.Literal("help"),
+    Type.Literal("external"),
+  ],
+  { description: "Sage domain namespace" },
+);
+
+type SageCodeModeRequest = {
+  domain: string;
+  action: string;
+  params?: Record<string, unknown>;
 };
 
+/**
+ * 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 +466,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) {
@@ -250,94 +496,53 @@ 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 [];
+async function sageSearch(req: SageCodeModeRequest): Promise<unknown> {
+  if (!sageBridge?.isReady()) {
+    throw new Error(
+      "MCP bridge not connected. The sage subprocess may have crashed — try restarting the plugin.",
+    );
   }
+  return sageBridge.callTool("sage_search", {
+    domain: req.domain,
+    action: req.action,
+    params: req.params ?? {},
+  });
 }
 
-/**
- * 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}`);
+async function sageExecute(req: SageCodeModeRequest): Promise<unknown> {
+  if (!sageBridge?.isReady()) {
+    throw new Error(
+      "MCP bridge not connected. The sage subprocess may have crashed — try restarting the plugin.",
+    );
   }
+  return sageBridge.callTool("sage_execute", {
+    domain: req.domain,
+    action: req.action,
+    params: req.params ?? {},
+  });
 }
 
 // ── Plugin Definition ────────────────────────────────────────────────────────
 
 let sageBridge: McpBridge | null = null;
-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)",
+    "Sage MCP tools for prompts, skills, governance, and external tool routing after hub-managed servers are started",
 
   register(api: PluginApi) {
     const pluginCfg = api.pluginConfig ?? {};
-    const sageBinary = typeof pluginCfg.sageBinary === "string" && pluginCfg.sageBinary.trim()
-      ? pluginCfg.sageBinary.trim()
-      : "sage";
+    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;
@@ -345,6 +550,17 @@ const plugin = {
     const minPromptLen = clampInt(pluginCfg.minPromptLen, 12, 0, 500);
     const maxPromptBytes = clampInt(pluginCfg.maxPromptBytes, 16_384, 512, 65_536);
 
+    // Heartbeat context-aware suggestions
+    const heartbeatContextSuggest = pluginCfg.heartbeatContextSuggest !== false;
+    const heartbeatSuggestCooldownMs =
+      clampInt(pluginCfg.heartbeatSuggestCooldownMinutes, 90, 10, 1440) * 60_000;
+    const heartbeatContextMaxChars = clampInt(
+      pluginCfg.heartbeatContextMaxChars,
+      4000,
+      500,
+      16_000,
+    );
+
     // Injection guard (opt-in)
     const injectionGuardEnabled = pluginCfg.injectionGuardEnabled === true;
     const injectionGuardMode = pluginCfg.injectionGuardMode === "block" ? "block" : "warn";
@@ -354,9 +570,21 @@ const plugin = {
     const injectionGuardScanGetPrompt = injectionGuardEnabled
       ? pluginCfg.injectionGuardScanGetPrompt !== false
       : false;
-    const injectionGuardUsePromptGuard = injectionGuardEnabled && pluginCfg.injectionGuardUsePromptGuard === true;
+    const injectionGuardUsePromptGuard =
+      injectionGuardEnabled && pluginCfg.injectionGuardUsePromptGuard === true;
     const injectionGuardMaxChars = clampInt(pluginCfg.injectionGuardMaxChars, 32_768, 256, 200_000);
-    const injectionGuardIncludeEvidence = injectionGuardEnabled && pluginCfg.injectionGuardIncludeEvidence === true;
+    const injectionGuardIncludeEvidence =
+      injectionGuardEnabled && pluginCfg.injectionGuardIncludeEvidence === true;
+
+    // Soul stream sync: read locally-synced soul document if configured
+    const soulStreamDao =
+      typeof pluginCfg.soulStreamDao === "string" && pluginCfg.soulStreamDao.trim()
+        ? pluginCfg.soulStreamDao.trim().toLowerCase()
+        : "";
+    const soulStreamLibraryId =
+      typeof pluginCfg.soulStreamLibraryId === "string" && pluginCfg.soulStreamLibraryId.trim()
+        ? pluginCfg.soulStreamLibraryId.trim()
+        : "soul";
 
     const scanCache = new Map<string, { ts: number; scan: SecurityScanResult }>();
     const SCAN_CACHE_LIMIT = 256;
@@ -373,12 +601,16 @@ const plugin = {
       if (cached && now - cached.ts < SCAN_CACHE_TTL_MS) return cached.scan;
 
       try {
-        const raw = await sageBridge.callTool("security_scan_text", {
-          text: trimmed,
-          maxChars: injectionGuardMaxChars,
-          maxEvidenceLen: 100,
-          includeEvidence: injectionGuardIncludeEvidence,
-          usePromptGuard: injectionGuardUsePromptGuard,
+        const raw = await sageSearch({
+          domain: "security",
+          action: "scan",
+          params: {
+            text: trimmed,
+            maxChars: injectionGuardMaxChars,
+            maxEvidenceLen: 100,
+            includeEvidence: injectionGuardIncludeEvidence,
+            usePromptGuard: injectionGuardUsePromptGuard,
+          },
         });
         const json = extractJsonFromMcpResult(raw) as any;
         const scan: SecurityScanResult = (json && typeof json === "object" ? json : {}) as any;
@@ -395,13 +627,165 @@ 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;
+
+    // ── Capture hooks (best-effort) ───────────────────────────────────
+    // These run the CLI capture hook in a child process. They are intentionally
+    // non-blocking for agent UX; failures are logged and ignored.
+    const captureHooksEnabled = process.env.SAGE_CAPTURE_HOOKS !== "0";
+    const CAPTURE_TIMEOUT_MS = 8_000;
+    const captureState = {
+      sessionId: "",
+      model: "",
+      provider: "",
+      lastPromptHash: "",
+      lastPromptTs: 0,
+    };
+
+    const runCaptureHook = async (
+      phase: "prompt" | "response",
+      extraEnv: Record<string, string>,
+    ): Promise<void> => {
+      await new Promise<void>((resolve, reject) => {
+        const child = spawn(sageBinary, ["capture", "hook", phase], {
+          env: { ...process.env, ...sageEnv, ...extraEnv },
+          stdio: ["ignore", "ignore", "pipe"],
+        });
+
+        let stderr = "";
+        child.stderr?.on("data", (chunk) => {
+          stderr += chunk.toString();
+        });
+
+        const timer = setTimeout(() => {
+          child.kill("SIGKILL");
+          reject(new Error(`capture hook timeout (${phase})`));
+        }, CAPTURE_TIMEOUT_MS);
+
+        child.on("error", (err) => {
+          clearTimeout(timer);
+          reject(err);
+        });
+
+        child.on("close", (code) => {
+          clearTimeout(timer);
+          if (code === 0 || code === null) {
+            resolve();
+            return;
+          }
+          reject(
+            new Error(`capture hook exited with code ${code}${stderr ? `: ${stderr.trim()}` : ""}`),
+          );
+        });
+      });
+    };
+
+    const capturePromptFromEvent = (hookName: string, event: any): void => {
+      if (!captureHooksEnabled) return;
+
+      const prompt = normalizePrompt(extractEventPrompt(event), { maxBytes: maxPromptBytes });
+      if (!prompt) return;
+
+      const sessionId = extractEventSessionId(event);
+      const model = extractEventModel(event);
+      const provider = extractEventProvider(event);
+
+      const promptHash = sha256Hex(`${sessionId}:${prompt}`);
+      const now = Date.now();
+      if (captureState.lastPromptHash === promptHash && now - captureState.lastPromptTs < 2_000) {
+        return;
+      }
+      captureState.lastPromptHash = promptHash;
+      captureState.lastPromptTs = now;
+      captureState.sessionId = sessionId || captureState.sessionId;
+      captureState.model = model || captureState.model;
+      captureState.provider = provider || captureState.provider;
+
+      const attributes = {
+        openclaw: {
+          hook: hookName,
+          sessionId: sessionId || undefined,
+        },
+      };
+
+      void runCaptureHook("prompt", {
+        SAGE_SOURCE: "openclaw",
+        OPENCLAW: "1",
+        PROMPT: prompt,
+        SAGE_SESSION_ID: sessionId || "",
+        SAGE_MODEL: model || "",
+        SAGE_PROVIDER: provider || "",
+        SAGE_CAPTURE_ATTRIBUTES_JSON: JSON.stringify(attributes),
+      }).catch((err) => {
+        api.logger.warn(
+          `[sage-capture] prompt capture failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      });
+    };
+
+    const captureResponseFromEvent = (hookName: string, event: any): void => {
+      if (!captureHooksEnabled) return;
+
+      const response = normalizePrompt(extractEventResponse(event), { maxBytes: maxPromptBytes });
+      if (!response) return;
+
+      const sessionId = extractEventSessionId(event) || captureState.sessionId;
+      const model = extractEventModel(event) || captureState.model;
+      const provider = extractEventProvider(event) || captureState.provider;
+      const tokensInput = extractEventTokenCount(event, "input");
+      const tokensOutput = extractEventTokenCount(event, "output");
+
+      const attributes = {
+        openclaw: {
+          hook: hookName,
+          sessionId: sessionId || undefined,
+        },
+      };
+
+      void runCaptureHook("response", {
+        SAGE_SOURCE: "openclaw",
+        OPENCLAW: "1",
+        SAGE_RESPONSE: response,
+        LAST_RESPONSE: response,
+        TOKENS_INPUT: tokensInput,
+        TOKENS_OUTPUT: tokensOutput,
+        SAGE_SESSION_ID: sessionId || "",
+        SAGE_MODEL: model || "",
+        SAGE_PROVIDER: provider || "",
+        SAGE_CAPTURE_ATTRIBUTES_JSON: JSON.stringify(attributes),
+      }).catch((err) => {
+        api.logger.warn(
+          `[sage-capture] response capture failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      });
+    };
+
+    // 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}`));
@@ -417,65 +801,26 @@ const plugin = {
           ctx.logger.info("Sage MCP bridge ready");
 
           const tools = await sageBridge!.listTools();
-          ctx.logger.info(`Discovered ${tools.length} internal MCP tools`);
+          ctx.logger.info(`Discovered ${tools.length} Sage MCP tools`);
 
-          for (const tool of tools) {
-            registerMcpTool(api, "sage", sageBridge!, tool, {
-              injectionGuardScanGetPrompt,
-              injectionGuardMode,
-              scanText,
-            });
-          }
+          registerCodeModeTools(api, {
+            injectionGuardEnabled,
+            injectionGuardScanGetPrompt,
+            injectionGuardMode,
+            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)}`,
           );
         }
-
-        // 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, {
-                injectionGuardScanGetPrompt: false,
-                injectionGuardMode: "warn",
-                scanText,
-              });
-            }
-          } 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 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();
       },
@@ -484,9 +829,9 @@ const plugin = {
     // 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,
-      });
+      capturePromptFromEvent("before_agent_start", event);
+
+      const prompt = normalizePrompt(extractEventPrompt(event), { maxBytes: maxPromptBytes });
       let guardNotice = "";
       if (injectionGuardScanAgentPrompt && prompt) {
         const scan = await scanText(prompt);
@@ -501,20 +846,79 @@ const plugin = {
         }
       }
 
+      // Read locally-synced soul document (written by `sync_library_stream` tool)
+      let soulContent = "";
+      if (soulStreamDao) {
+        const xdgData = process.env.XDG_DATA_HOME || join(homedir(), ".local", "share");
+        const soulPath = join(
+          xdgData,
+          "sage",
+          "souls",
+          `${soulStreamDao}-${soulStreamLibraryId}.md`,
+        );
+        try {
+          if (existsSync(soulPath)) {
+            soulContent = readFileSync(soulPath, "utf8").trim();
+          }
+        } catch {
+          // Soul file unreadable — skip silently
+        }
+      }
+
       if (!prompt || prompt.length < minPromptLen) {
         const parts: string[] = [];
-        if (autoInject) parts.push(SAGE_CONTEXT);
+        if (soulContent) parts.push(soulContent);
+        if (autoInject) parts.push(SAGE_FULL_CONTEXT);
         if (guardNotice) parts.push(guardNotice);
         return parts.length ? { prependContext: parts.join("\n\n") } : undefined;
       }
 
       let suggestBlock = "";
-      if (autoSuggest && sageBridge) {
+      const isHeartbeat = isHeartbeatPrompt(prompt);
+
+      if (isHeartbeat && heartbeatContextSuggest && sageBridge?.isReady()) {
+        const now = Date.now();
+        const cooldownElapsed =
+          now - heartbeatSuggestState.lastFullAnalysisTs >= heartbeatSuggestCooldownMs;
+
+        if (cooldownElapsed) {
+          api.logger.info("[heartbeat-context] Running full context-aware skill analysis");
+          try {
+            const context = await gatherHeartbeatContext(
+              sageBridge,
+              api.logger,
+              heartbeatContextMaxChars,
+            );
+            if (context) {
+              suggestBlock = await searchSkillsForContext(
+                sageBridge,
+                context,
+                suggestLimit,
+                api.logger,
+              );
+              heartbeatSuggestState.lastFullAnalysisTs = now;
+              heartbeatSuggestState.lastSuggestions = suggestBlock;
+            }
+          } catch (err) {
+            api.logger.warn(
+              `[heartbeat-context] Full analysis failed: ${err instanceof Error ? err.message : String(err)}`,
+            );
+          }
+        } else {
+          suggestBlock = heartbeatSuggestState.lastSuggestions;
+        }
+      }
+
+      if (!suggestBlock && autoSuggest && sageBridge?.isReady()) {
         try {
-          const raw = await sageBridge.callTool("search_skills", {
-            query: prompt,
-            source: "all",
-            limit: Math.max(20, suggestLimit),
+          const raw = await sageSearch({
+            domain: "skills",
+            action: "search",
+            params: {
+              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[]) : [];
@@ -525,41 +929,199 @@ const plugin = {
       }
 
       const parts: string[] = [];
-      if (autoInject) parts.push(SAGE_CONTEXT);
+      if (soulContent) parts.push(soulContent);
+      if (autoInject) parts.push(SAGE_FULL_CONTEXT);
       if (guardNotice) parts.push(guardNotice);
       if (suggestBlock) parts.push(suggestBlock);
 
       if (!parts.length) return undefined;
       return { prependContext: parts.join("\n\n") };
     });
+
+    api.on("after_agent_response", async (event: any) => {
+      captureResponseFromEvent("after_agent_response", event);
+    });
+
+    // Legacy OpenClaw hook names observed in older runtime builds.
+    api.on("message_received", async (event: any) => {
+      capturePromptFromEvent("message_received", event);
+    });
+    api.on("agent_end", async (event: any) => {
+      captureResponseFromEvent("agent_end", event);
+    });
   },
 };
 
-function registerMcpTool(
+/** 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 privy\` (or \`sage wallet connect\`) to configure a wallet, or set KEYSTORE_PASSWORD for automated flows.`;
+  }
+  // Privy session/auth issues
+  if (/privy|session.*expired|re-authenticate|wallet session expired/i.test(msg)) {
+    return `${msg}\n\nHint: Reconnect with login-code flow:\n  \`sage wallet connect privy --force --device-code\`\nThen verify:\n  \`sage wallet current\`\n  \`sage daemon status\``;
+  }
+  // Auth / token issues
+  if (/auth|unauthorized|403|401|token.*expired|challenge/i.test(msg)) {
+    if (/ipfs|upload token|pin|credits/i.test(msg) || /ipfs|upload|pin|credit/i.test(toolName)) {
+      return `${msg}\n\nHint: Run \`sage config ipfs setup\` to refresh authentication, or check SAGE_IPFS_UPLOAD_TOKEN.`;
+    }
+    return `${msg}\n\nHint: Reconnect wallet auth with:\n  \`sage wallet connect privy --force --device-code\``;
+  }
+  // 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 config ipfs faucet\` (testnet; legacy: \`sage ipfs faucet\`) 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;
+
+        // Try to get wallet + network info from sage
+        let walletInfo = "unknown";
+        let networkInfo = "unknown";
+        if (bridgeReady && sageBridge) {
+          try {
+            const ctx = await sageSearch({
+              domain: "meta",
+              action: "get_project_context",
+              params: {},
+            });
+            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,
+          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 registerCodeModeTools(
   api: PluginApi,
-  prefix: string,
-  bridge: McpBridge,
-  tool: McpToolDef,
-  opts?: {
+  opts: {
+    injectionGuardEnabled: boolean;
     injectionGuardScanGetPrompt: boolean;
     injectionGuardMode: "warn" | "block";
     scanText: (text: string) => Promise<SecurityScanResult | null>;
   },
 ) {
-  const name = `${prefix}_${tool.name}`;
-  const schema = mcpSchemaToTypebox(tool.inputSchema);
+  api.registerTool(
+    {
+      name: "sage_search",
+      label: "Sage: search",
+      description: "Sage code-mode search/discovery (domain/action routing)",
+      parameters: Type.Object({
+        domain: SageDomain,
+        action: Type.String(),
+        params: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+      }),
+      execute: async (_toolCallId: string, params: Record<string, unknown>) => {
+        try {
+          const domain = String(params.domain ?? "");
+          const action = String(params.action ?? "");
+          const p =
+            params.params && typeof params.params === "object"
+              ? (params.params as Record<string, unknown>)
+              : {};
+
+          if (domain === "external" && !["list_servers", "search"].includes(action)) {
+            return toToolResult({
+              error: "For external domain, sage_search only supports actions: list_servers, search",
+            });
+          }
+
+          const result = await sageSearch({ domain, action, params: p });
+          return toToolResult(result);
+        } catch (err) {
+          const enriched = enrichErrorMessage(
+            err instanceof Error ? err : new Error(String(err)),
+            "sage_search",
+          );
+          return toToolResult({ error: enriched });
+        }
+      },
+    },
+    { name: "sage_search", optional: true },
+  );
 
   api.registerTool(
     {
-      name,
-      label: `${prefix}: ${tool.name}`,
-      description: tool.description ?? `MCP tool: ${prefix}/${tool.name}`,
-      parameters: schema,
+      name: "sage_execute",
+      label: "Sage: execute",
+      description: "Sage code-mode execute/mutations (domain/action routing)",
+      parameters: Type.Object({
+        domain: SageDomain,
+        action: Type.String(),
+        params: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+      }),
       execute: async (_toolCallId: string, params: Record<string, unknown>) => {
         try {
-          const result = await bridge.callTool(tool.name, params);
+          const domain = String(params.domain ?? "");
+          const action = String(params.action ?? "");
+          const p =
+            params.params && typeof params.params === "object"
+              ? (params.params as Record<string, unknown>)
+              : {};
+
+          if (opts.injectionGuardEnabled) {
+            const scan = await opts.scanText(JSON.stringify({ domain, action, params: p }));
+            if (scan?.shouldBlock) {
+              const summary = formatSecuritySummary(scan);
+              if (opts.injectionGuardMode === "block") {
+                return toToolResult({ error: `Blocked by injection guard: ${summary}` });
+              }
+              api.logger.warn(`[injection-guard] warn: ${summary}`);
+            }
+          }
 
-          if (opts?.injectionGuardScanGetPrompt && tool.name === "get_prompt" && prefix === "sage") {
+          if (domain === "external" && !["execute", "call"].includes(action)) {
+            return toToolResult({
+              error: "For external domain, sage_execute only supports actions: execute, call",
+            });
+          }
+
+          const result = await sageExecute({ domain, action, params: p });
+
+          if (opts.injectionGuardScanGetPrompt && domain === "prompts" && action === "get") {
             const json = extractJsonFromMcpResult(result) as any;
             const content =
               typeof json?.prompt?.content === "string"
@@ -578,12 +1140,8 @@ function registerMcpTool(
                   );
                 }
 
-                // Warn mode: attach a compact summary to the JSON output.
                 if (json && typeof json === "object") {
-                  json.security = {
-                    shouldBlock: true,
-                    summary,
-                  };
+                  json.security = { shouldBlock: true, summary };
                   return {
                     content: [{ type: "text" as const, text: JSON.stringify(json) }],
                     details: result,
@@ -595,21 +1153,27 @@ 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)),
+            "sage_execute",
+          );
+          return toToolResult({ error: enriched });
         }
       },
     },
-    { name, optional: true },
+    { name: "sage_execute", optional: true },
   );
 }
 
 export default plugin;
 
 export const __test = {
-  SAGE_CONTEXT,
+  PKG_VERSION,
+  SAGE_CONTEXT: SAGE_FULL_CONTEXT,
   normalizePrompt,
   extractJsonFromMcpResult,
   formatSkillSuggestions,
+  mcpSchemaToTypebox,
+  jsonSchemaToTypebox,
+  enrichErrorMessage,
 };