@sage-protocol/openclaw-sage 0.1.8 → 0.1.10

package/README.md

@@ -5,19 +5,56 @@ MCP bridge plugin that exposes Sage Protocol tools inside OpenClaw via Code Mode
 ## What It Does
 
 - **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
+- **Agent Profile (Identity Context)** - Injects wallet, active libraries, and skill counts into every turn so the agent knows who it's working for
+- **Auto-Context Injection** - Injects Sage tool context and skill suggestions via `before_prompt_build` with stable context cached separately from per-turn dynamic context
 - **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
 
+## Agent Profile (Identity Context)
+
+Every OpenClaw session automatically gets Sage Protocol identity context injected via the `before_prompt_build` hook. Stable context (protocol description, identity, tool docs) goes in `prependSystemContext` so providers can cache it across turns. Dynamic content (skill suggestions, security guard) goes in `prependContext` and refreshes each turn.
+
+Example of what gets injected:
+
+```
+## Sage Protocol Context
+Sage Protocol is a decentralized network for collaborative prompt, skill, and knowledge
+curation on Base (L2). Skills and prompts live in libraries governed by DAOs. Creators
+and curators earn when their work is used. SXXX is the governance token: hold it to
+vote, create DAOs, and shape the protocol. Burns from activity create deflationary
+pressure — early participants gain governance influence and economic upside as the
+network grows. The more skills published, the more valuable discovery becomes for every
+user and agent.
+
+### Active Identity
+- Wallet: 0x9794...507ca (privy, Base Sepolia)
+- Active libraries (6): sage-entrypoints, impeccable-ui-review, sage-review-foundations, ...
+- Libraries: 10 installed (48 skills, 12 prompts)
+```
+
+The context is fetched from the sage CLI (`wallet current`, `library active`, `library list`) and cached for 60 seconds. If the CLI is unavailable or any query fails, the identity block is silently omitted.
+
 ## Install
 
+```bash
+sage init --openclaw
+```
+
+This is the recommended product path: it installs the bundled OpenClaw plugin, the companion Sage
+skills, and only the scan-only internal hooks.
+
+If you only want the raw plugin package flow, you can still run:
+
 ```bash
 openclaw plugins install @sage-protocol/openclaw-sage
 ```
 
 After install, **restart the Gateway** for the plugin to take effect.
 
+CI validates the packed tarball against the latest published `openclaw` CLI by running
+`npx openclaw@latest plugins install` in an isolated `OPENCLAW_HOME`.
+
 ### Verify
 
 ```bash
@@ -33,6 +70,35 @@ openclaw plugins update openclaw-sage
 openclaw plugins update --all
 ```
 
+### Auto-Enable
+
+The plugin sets `enabledByDefault: true` in its manifest, so it auto-enables when referenced in `openclaw.json` config without needing a manual `plugins.allow` entry.
+
+### Hook Priority
+
+The `before_prompt_build` hook runs at priority 90 (higher = earlier). This ensures Sage's stable system context (protocol description, wallet identity, tool docs) is the base layer that other plugins build on. Dynamic per-turn content (skill suggestions, security guards) goes in `prependContext`.
+
+### Secrets Management
+
+Sage credentials support OpenClaw's SecretRef system instead of raw environment variables:
+
+```json5
+{
+  "secrets": {
+    "providers": {
+      "default": { "source": "env", "allowlist": ["SAGE_*", "KEYSTORE_*"] }
+    }
+  }
+}
+```
+
+The plugin declares three SecretRef-compatible credentials:
+- `SAGE_IPFS_UPLOAD_TOKEN` — Bearer token for Worker API auth
+- `KEYSTORE_PASSWORD` — Wallet keystore password (non-interactive)
+- `SAGE_DELEGATE_KEYSTORE_PASSWORD` — Delegate keystore password (daemon/operator)
+
+These are resolved through OpenClaw's secret provider chain (env, file, or exec) rather than passed as raw env vars.
+
 ### Login With Code (Privy Device-Code)
 
 If browser OAuth is unreliable, use:
@@ -96,7 +162,7 @@ sage bounties create --mode direct --assignee 0x... --title "Task" --description
 
 ### 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`).
+This plugin uses OpenClaw's plugin hook API to inject context at the start of each prompt build via `before_prompt_build`.
 
 Available config fields:
 
@@ -151,7 +217,9 @@ Notes:
 
 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.
+- `sage init --openclaw` now defaults to plugin-first setup and only installs scan-only hooks, so duplicate injection should not happen by default.
+- Only `sage init --openclaw --mode hooks` installs the legacy `agent:bootstrap` injection hook.
+- If you deliberately re-enable bootstrap injection alongside the plugin, disable it with `SAGE_OPENCLAW_INJECT_CONTEXT=0`.
 
 The internal hook now also scans `command:new` and `command:stop` through `sage security scan-hook` and prepends warnings when suspicious content is detected.
 

package/dist/index.d.ts

@@ -0,0 +1,79 @@
+import { type TSchema } from "@sinclair/typebox";
+/**
+ * Minimal type stubs for OpenClaw plugin API.
+ *
+ * OpenClaw's jiti runtime resolves "openclaw/plugin-sdk" at load time.
+ * These stubs keep the code compilable standalone.
+ */
+type PluginLogger = {
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+};
+type PluginServiceContext = {
+    config: unknown;
+    workspaceDir?: string;
+    stateDir: string;
+    logger: PluginLogger;
+};
+type PluginApi = {
+    id: string;
+    name: string;
+    logger: PluginLogger;
+    pluginConfig?: Record<string, unknown>;
+    registerTool: (tool: unknown, opts?: {
+        name?: string;
+        optional?: boolean;
+    }) => void;
+    registerService: (service: {
+        id: string;
+        start: (ctx: PluginServiceContext) => void | Promise<void>;
+        stop?: (ctx: PluginServiceContext) => void | Promise<void>;
+    }) => void;
+    on: (hook: string, handler: (...args: unknown[]) => unknown | Promise<unknown>, opts?: {
+        priority?: number;
+    }) => void;
+};
+declare function normalizePrompt(prompt: string, opts?: {
+    maxBytes?: number;
+}): string;
+declare function extractJsonFromMcpResult(result: unknown): unknown;
+type SkillSearchResult = {
+    key?: string;
+    name?: string;
+    description?: string;
+    source?: string;
+    library?: string;
+    mcpServers?: string[];
+};
+declare function formatSkillSuggestions(results: SkillSearchResult[], limit: number): string;
+/**
+ * Convert a single MCP JSON Schema property into a TypeBox type.
+ * Handles nested objects, typed arrays, and enums.
+ */
+declare function jsonSchemaToTypebox(prop: Record<string, unknown>): TSchema;
+/**
+ * Convert an MCP JSON Schema inputSchema into a TypeBox object schema
+ * that OpenClaw's tool system accepts.
+ */
+declare function mcpSchemaToTypebox(inputSchema?: Record<string, unknown>): import("@sinclair/typebox").TObject<{}>;
+declare const plugin: {
+    id: string;
+    name: string;
+    version: string;
+    description: string;
+    register(api: PluginApi): void;
+};
+/** Map common error patterns to actionable hints */
+declare function enrichErrorMessage(err: Error, toolName: string): string;
+export default plugin;
+export declare const __test: {
+    PKG_VERSION: string;
+    SAGE_CONTEXT: string;
+    normalizePrompt: typeof normalizePrompt;
+    extractJsonFromMcpResult: typeof extractJsonFromMcpResult;
+    formatSkillSuggestions: typeof formatSkillSuggestions;
+    mcpSchemaToTypebox: typeof mcpSchemaToTypebox;
+    jsonSchemaToTypebox: typeof jsonSchemaToTypebox;
+    enrichErrorMessage: typeof enrichErrorMessage;
+};