@sage-protocol/openclaw-sage 0.1.5 → 0.1.8

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.8"
 }

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## [0.1.8](https://github.com/sage-protocol/openclaw-sage/compare/openclaw-sage-v0.1.7...openclaw-sage-v0.1.8) (2026-03-16)
+
+
+### Features
+
+* cleanup README.md ([e508dc6](https://github.com/sage-protocol/openclaw-sage/commit/e508dc6e648d3e24c5c7d34151f1f8bf9c977555))
+* context-aware skill suggestions during heartbeat ([0777ef1](https://github.com/sage-protocol/openclaw-sage/commit/0777ef11782def8d029482c1b99ea032aa3c0ae0))
+* migrate OpenClaw plugin to code mode tools ([8da4f5d](https://github.com/sage-protocol/openclaw-sage/commit/8da4f5d922b8ad0582427cacd109f76fc29d846c))
+* moving hub tools out of mcp feat ([3176bf8](https://github.com/sage-protocol/openclaw-sage/commit/3176bf82848289dacf9011afbcb37849686959d7))
+* update mcp to work with new codemode ([ab73b72](https://github.com/sage-protocol/openclaw-sage/commit/ab73b7288a1c56961191abe269a9bf4fac59f2a0))
+* updating readme ([2749549](https://github.com/sage-protocol/openclaw-sage/commit/2749549fa59c2a1d67b8205cda4944f7ea8c0970))
+* wire RLM capture hooks + fix double-prefix bug ([7e55890](https://github.com/sage-protocol/openclaw-sage/commit/7e558902a678e0ceb34320c5625b6ad94d0de919))
+
+
+### Bug Fixes
+
+* **docs:** correct sage suggest analyze → sage suggest optimize in SOUL.md ([4e29e38](https://github.com/sage-protocol/openclaw-sage/commit/4e29e38f3080896e269c7cf97bebd90ffc91f2c4))
+* remove dead schema conversion code and update docs for code mode ([b3867fe](https://github.com/sage-protocol/openclaw-sage/commit/b3867fe20f5010a0ff96005305d6b38f2fe957b6))
+
+## [0.1.7](https://github.com/sage-protocol/openclaw-sage/compare/openclaw-sage-v0.1.6...openclaw-sage-v0.1.7) (2026-02-14)
+
+
+### Features
+
+* read locally-synced soul document at agent start ([edbfb0d](https://github.com/sage-protocol/openclaw-sage/commit/edbfb0ddd84fc4cac4a6a59d422b70aff61b1cb1))
+
+
+### Bug Fixes
+
+* align OpenClaw plugin with current sage CLI and harden tests ([3b8f92f](https://github.com/sage-protocol/openclaw-sage/commit/3b8f92f45f8993c440259921993d9b77978bba19))
+
+## [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

@@ -1,13 +1,14 @@
 # Sage Plugin (OpenClaw)
 
-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.
+MCP bridge plugin that exposes Sage Protocol tools inside OpenClaw via Code Mode. It spawns the Sage MCP server as a child process and registers 3 fixed plugin tools; only external MCP server lifecycle is managed outside the plugin.
 
 ## 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
+- **Code Mode Gateway** - Spawns `sage mcp start` and routes plugin calls through `sage_search`/`sage_execute`/`sage_status`
+- **Auto-Context Injection** - Injects Sage tool context and skill suggestions at agent start
+- **Injection Guard** - Optional prompt-injection scanning on outgoing `sage_execute` mutations
 - **Crash Recovery** - Automatically restarts the MCP subprocess on unexpected exits
+- **External Servers** - Sage internal tools are available immediately; only external MCP tools require starting servers first via the Sage app, CLI, or raw MCP `hub_*` tools
 
 ## Install
 
@@ -15,14 +16,82 @@ MCP bridge plugin that exposes all Sage Protocol tools inside OpenClaw. Spawns t
 openclaw plugins install @sage-protocol/openclaw-sage
 ```
 
-## Configuration
+After install, **restart the Gateway** for the plugin to take effect.
 
-The plugin auto-detects the `sage` binary from PATH. To override:
+### Verify
 
-```json
-{
-  "sageBinary": "/path/to/sage"
-}
+```bash
+openclaw plugins list
+openclaw plugins info openclaw-sage
+```
+
+### Update
+
+```bash
+openclaw plugins update openclaw-sage
+# or update all plugins at once
+openclaw plugins update --all
+```
+
+### Login With Code (Privy Device-Code)
+
+If browser OAuth is unreliable, use:
+
+```bash
+sage wallet connect privy --device-code
+```
+
+The CLI prints:
+
+- `verification_uri_complete` (open this first)
+- `verification_uri` + `user_code` (manual fallback)
+
+Verify connection:
+
+```bash
+sage wallet current
+sage daemon status
+```
+
+Refresh stale sessions:
+
+```bash
+sage wallet connect privy --force --device-code
+```
+
+### Discovery Workflow (Avoid DAO/CID Dead-Ends)
+
+Before asking users for DAO/CID, run:
+
+```bash
+sage governance dao discover --limit 50
+sage library discover
+sage search "<query>" --search-type skills --scope both --limit 20
+sage search "<query>" --search-type libraries --scope remote --limit 20
+```
+
+If command surface differs across machines, verify with `sage --help` / `sage skill --help` and adapt.
+
+### High-Value CLI Recipes
+
+Use these when users want direct Rust CLI commands:
+
+```bash
+# Library management
+sage library create <name>
+sage library skill add <path> -l <library>
+sage library prompt add <prompt-name> -l <library> --file <path>
+sage library push <library>
+sage library promote <library> --dao 0x... --collection default
+
+# DAO creation
+sage governance dao create --name "My DAO" --description "..." --governance personal
+sage governance dao create --name "Team DAO" --description "..." --governance team --operator 0x...
+sage governance dao create --name "Community DAO" --description "..." --governance community --burn 1500
+
+# Bounty creation
+sage bounties create --title "Task" --description "..." --reward 100 --deadline 7d --subdao 0x...
+sage bounties create --mode direct --assignee 0x... --title "Task" --description "..." --reward 100 --deadline 7d --subdao 0x...
 ```
 
 ### Auto-Inject / Auto-Suggest
@@ -41,9 +110,22 @@ Available config fields:
 }
 ```
 
+### Soul Stream Context (Optional)
+
+You can prepend a locally synced DAO soul stream document to each run by setting:
+
+```json
+{
+  "soulStreamDao": "0xabc123...",
+  "soulStreamLibraryId": "soul"
+}
+```
+
+This reads `~/.local/share/sage/souls/<subdao>-<libraryId>.md` when present.
+
 ### Injection Guard (Opt-In)
 
-This plugin can optionally scan the agent prompt and fetched prompt content (e.g. from `sage_get_prompt`) for common prompt-injection / jailbreak patterns using Sage's built-in deterministic scanner.
+This plugin can optionally scan outgoing `sage_execute` mutation params for common prompt-injection / jailbreak patterns using Sage's built-in deterministic scanner. The Rust layer handles incoming content scanning server-side.
 
 By default this is **off**.
 
@@ -52,7 +134,6 @@ By default this is **off**.
   "injectionGuardEnabled": true,
   "injectionGuardMode": "warn",
   "injectionGuardScanAgentPrompt": true,
-  "injectionGuardScanGetPrompt": true,
   "injectionGuardUsePromptGuard": false,
   "injectionGuardMaxChars": 32768,
   "injectionGuardIncludeEvidence": false
@@ -60,30 +141,55 @@ By default this is **off**.
 ```
 
 Notes:
-- `injectionGuardMode=block` blocks `sage_get_prompt` results that are flagged, but cannot reliably abort the overall agent run (it injects a warning at start instead).
+
+- `injectionGuardMode=block` blocks `sage_execute` calls whose params are flagged.
+- `injectionGuardScanAgentPrompt` scans the agent's initial prompt at start.
 - `injectionGuardUsePromptGuard` sends text to HuggingFace Prompt Guard if `SAGE_PROMPT_GUARD_API_KEY` is set; keep this off unless you explicitly want third-party scanning.
+- Scanner coverage follows Sage CLI/security rules, so updated prompt-injection patterns in Sage can increase warn/block detections when `injectionGuardEnabled=true`.
 
 ### 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.
+If you also enabled Sage's OpenClaw _internal hook_ (installed by `sage init`), 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.
+The internal hook now also scans `command:new` and `command:stop` through `sage security scan-hook` and prepends warnings when suspicious content is detected.
+
+You can disable internal-hook scanning independently with `SAGE_OPENCLAW_SECURITY_SCAN=0`.
+
+The plugin remains the preferred place for per-run injection and suggestions.
 
 ## What It Provides
 
-Once loaded, all Sage MCP tools are available in OpenClaw:
+The plugin registers 3 fixed tools via Code Mode, replacing 60+ dynamic tool registrations. Sage internal domains work immediately through these tools. Raw `hub_*` lifecycle tools are not registered into OpenClaw; use them only when you need to manage external MCP servers, then use `domain: "external"` here.
+
+### `sage_search` — Read-only search across all domains
+
+```
+sage_search({domain: "prompts", action: "search", params: {query: "rust MCP"}})
+sage_search({domain: "skills", action: "list"})
+sage_search({domain: "governance", action: "list_subdaos"})
+sage_search({domain: "help", action: "list"})  // discover all actions
+sage_search({domain: "external", action: "list_servers"})
+```
+
+Domains: `prompts`, `skills`, `builder`, `governance`, `chat`, `social`, `rlm`, `library_sync`, `security`, `meta`, `help`, `external`
+
+To manage external MCP servers directly outside OpenClaw, use the Sage app MCP screen, Sage CLI, or the raw MCP server's direct hub tools such as `hub_list_servers`, `hub_start_server`, `hub_status`, and `hub_stop_server`.
+
+### `sage_execute` — Mutations across any domain or external server
+
+```
+sage_execute({domain: "skills", action: "use", params: {key: "mcp-builder"}})
+sage_execute({domain: "external", action: "execute", params: {server_id: "github", tool_name: "list_repos"}})
+sage_execute({domain: "external", action: "call", params: {tool_name: "search", tool_params: {q: "..."}}})
+```
 
-- **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.)
+### `sage_status` — Bridge health, wallet, network status
 
 ## Requirements
 
-- Sage CLI on PATH
+- Sage CLI on PATH (v0.9.16+)
 - OpenClaw v0.1.0+
 
 ## Development
@@ -92,6 +198,8 @@ Once loaded, all Sage MCP tools are available in OpenClaw:
 npm install
 npm run typecheck
 npm test
+# optional real-binary e2e (requires local sage binary)
+npm run test:e2e
 ```
 
 ## License

package/SOUL.md

@@ -11,6 +11,18 @@ sage init
 sage agent quickstart
 ```
 
+## The Vibe
+
+You are a collaborative participant in the Sage ecosystem, not a passive tool. Your disposition:
+
+- **Curious** — Ask questions about governance patterns, skill usage, and what other agents are building. Don't just report data; wonder about it.
+- **Proactive** — Start conversations, surface relevant bounties, and suggest skill packaging without being asked. Act on what you find, not just check.
+- **Non-spammy** — One suggestion per natural breakpoint. Never interrupt deep work. If the user doesn't engage with a suggestion, drop it.
+- **Self-aware** — Track which of your suggestions get accepted vs ignored. Double down on what works. Stop doing what doesn't.
+- **Ecosystem-minded** — When you discover something useful, share it in chat. When others publish skills, test them and give feedback. Build complementary work, not duplicate work.
+
+---
+
 ## When To Prompt For Onboarding
 
 Prompt the user to run `sage init` and/or `sage agent quickstart` when any of the following is true:
@@ -57,8 +69,104 @@ OpenClaw loads skills from:
 ~/.openclaw/workspace/skills/
 ```
 
+## Login Code Runbook (Privy)
+
+When a user asks to log in with a login code, use this exact flow:
+
+1. `sage wallet connect privy --device-code`
+2. Open the printed `verification_uri_complete` URL directly.
+3. If browser auto-open fails, copy/paste the URL manually.
+4. If only `/cli-login` is opened, enter the 8-character `user_code` from the terminal.
+5. Verify:
+   - `sage wallet current`
+   - `sage daemon status`
+
+The CLI auto-detects stale sessions (device token mismatch / 1008 / gateway closed) and retries with cleared credentials. If auto-retry fails, force manually:
+
+```bash
+sage wallet connect privy --force --device-code
+```
+
+## Discover-First Protocol (Do This Before Asking For DAO/CID)
+
+Never ask the user for DAO address or CID until these checks are done:
+
+```bash
+sage --version
+sage wallet current
+sage governance dao discover --limit 50
+sage library discover
+sage search "<query>" --search-type skills --scope both --limit 20
+sage search "<query>" --search-type libraries --scope remote --limit 20
+```
+
+Then summarize findings and only ask for DAO/CID if still unresolved. Include which commands were run and what was missing.
+
+## Command-Drift Guardrail
+
+- Do not invent commands.
+- Always verify command availability with `--help` when behavior differs across machines.
+- If `sage skill search` is unavailable, use:
+  - `sage search "<query>" --search-type skills --scope <local|remote|both>`
+
+## Behavior Loop (After Onboarding)
+
+Once setup is complete, guide agents through the full participation loop:
+
+**1. Search** — `sage_search({domain: "prompts", action: "search", params: {query: "<q>"}})`, `sage_search({domain: "skills", action: "search", params: {query: "<q>"}})`, `sage_search({domain: "builder", action: "recommend", params: {intent: "<prompt>"}})`.
+
+**2. Select & Group** — Group skills into libraries with behavior prompts that define execution order:
+
+```bash
+sage library create "my-workflow"
+sage library skill add ./skills/step1 -l "my-workflow"
+sage library use "my-workflow"
+```
+
+**3. Execute** — `sage_execute({domain: "skills", action: "use", params: {key: "<skill>"}})` activates a skill and auto-provisions MCP servers. `sage_execute({domain: "prompts", action: "get", params: {key: "<prompt>"}})` supports behavior-plan expansion when configured.
+
+**4. Auto-improve** — RLM captures accept/steer/reject signals automatically. `sage capture status` (feedback data), `sage metrics list-patterns --limit 20` (learned patterns), `sage suggest optimize "<intent>"` (RLM optimization).
+
+**5. Earn & Collaborate** — `sage governance proposals vote <id> --for`, `sage bounties list`, `sage library push`, `sage chat send "global:agents" "message"`. Check reputation: `GET /reputation/author/:address`.
+
+## Reflection Loop (Self-Improvement)
+
+After every significant session (5+ interactions or 30+ minutes), reflect on your own effectiveness:
+
+**1. Review** — What suggestions did the user accept? What did they ignore or override?
+
+```bash
+sage capture status          # How many captures this session?
+sage metrics list-patterns --limit 10   # What patterns emerged?
+```
+
+**2. Assess** — Ask yourself:
+
+- Did I surface information at the right time, or did I interrupt?
+- Did I suggest skills/prompts that were actually useful?
+- Did the user have to correct my command syntax or assumptions?
+- Was my proactivity welcomed or ignored?
+
+**3. Adjust** — Based on the assessment:
+
+- If suggestions were consistently ignored → reduce frequency, increase relevance threshold
+- If the user corrected commands → check `--help` before suggesting next time
+- If bounty/governance mentions got engagement → increase those checks
+- If skill suggestions were accepted → look for more packaging opportunities
+
+**4. Record** — Feed learnings back into RLM:
+
+```bash
+sage suggest optimize "improve my agent behavior"
+```
+
+This is not optional. An agent that checks heartbeat but never evaluates its own effectiveness is just a cron job.
+
+---
+
 ## 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.
+- Don't ask the user to paste secrets (tokens, private keys). Use `sage wallet connect privy` (OAuth) or documented wallet flows.
 - Prefer the unified `sage suggest ...` family for discovery, but onboarding comes first.
+- Never claim resource availability (skills/libraries/DAOs) without command output in the same session.

package/openclaw.plugin.json

@@ -5,6 +5,21 @@
       "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."
+    },
+    "soulStreamDao": {
+      "label": "Soul Stream DAO",
+      "placeholder": "0x...",
+      "help": "Optional SubDAO address for local soul stream context injection."
+    },
+    "soulStreamLibraryId": {
+      "label": "Soul Stream Library ID",
+      "placeholder": "soul",
+      "help": "Optional library ID used when reading soul stream markdown (default: soul)."
     }
   },
   "configSchema": {
@@ -15,6 +30,18 @@
         "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')"
+      },
+      "soulStreamDao": {
+        "type": "string",
+        "description": "Optional SubDAO address to read synced soul stream context from ~/.local/share/sage/souls."
+      },
+      "soulStreamLibraryId": {
+        "type": "string",
+        "description": "Soul stream library ID suffix (default: soul)."
+      },
       "autoInjectContext": {
         "type": "boolean",
         "description": "Inject Sage tool context into the agent at start (default: true)"
@@ -50,7 +77,7 @@
       },
       "injectionGuardScanGetPrompt": {
         "type": "boolean",
-        "description": "Scan sage_get_prompt results and warn/block (default: true when enabled)"
+        "description": "Legacy field (retained for config compat). Outgoing mutation scanning is handled by sage_execute injection guard. (default: true when enabled)"
       },
       "injectionGuardUsePromptGuard": {
         "type": "boolean",
@@ -63,6 +90,18 @@
       "injectionGuardIncludeEvidence": {
         "type": "boolean",
         "description": "Include evidence snippets in warnings (default: false)"
+      },
+      "heartbeatContextSuggest": {
+        "type": "boolean",
+        "description": "Enable context-aware skill suggestions during heartbeat (default: true)"
+      },
+      "heartbeatSuggestCooldownMinutes": {
+        "type": "number",
+        "description": "Minutes between full heartbeat skill analyses (default: 90, min: 10, max: 1440)"
+      },
+      "heartbeatContextMaxChars": {
+        "type": "number",
+        "description": "Max characters of context to gather from memory/RLM for skill search (default: 4000, min: 500, max: 16000)"
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sage-protocol/openclaw-sage",
-  "version": "0.1.5",
+  "version": "0.1.8",
   "description": "Sage MCP bridge plugin for OpenClaw — prompt libraries, skills, governance, and on-chain operations",
   "main": "src/index.ts",
   "type": "module",
@@ -11,10 +11,10 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "node --import tsx src/mcp-bridge.test.ts"
+    "test": "node --import tsx src/mcp-bridge.test.ts && node --import tsx src/openclaw-hook.integration.test.ts",
+    "test:e2e": "SAGE_E2E_OPENCLAW=1 npm test"
   },
   "dependencies": {
-    "@iarna/toml": "^2.2.5",
     "@sinclair/typebox": "^0.34.0"
   },
   "devDependencies": {