openclaw-safeclaw-plugin 0.1.0 → 0.1.2

package/README.md

@@ -8,20 +8,23 @@ Neurosymbolic governance plugin for OpenClaw AI agents. Validates every tool cal
 npm install openclaw-safeclaw-plugin
 ```
 
-## Quick Start (SaaS)
+## Quick Start
 
-Point the plugin at the hosted SafeClaw service:
+Install and go — the plugin connects to SafeClaw's hosted service by default:
 
 ```bash
-export SAFECLAW_URL="https://api.safeclaw.eu/api/v1"
-export SAFECLAW_ENFORCEMENT="enforce"
+npm install openclaw-safeclaw-plugin
 ```
 
-No server setup needed — the plugin connects to SafeClaw's hosted service.
+No configuration needed. The default service URL is `https://api.safeclaw.eu/api/v1`.
+
+## Self-Hosted
 
-## Quick Start (Self-Hosted)
+To run your own SafeClaw service, override the URL:
 
 ```bash
+export SAFECLAW_URL="http://localhost:8420/api/v1"
+
 # Start the SafeClaw service
 git clone https://github.com/tendlyeu/SafeClaw.git
 cd SafeClaw/safeclaw-service
@@ -32,8 +35,6 @@ safeclaw serve
 # Engine ready on http://localhost:8420
 ```
 
-The plugin auto-connects to `http://localhost:8420/api/v1` by default.
-
 ## What It Does
 
 - **Blocks dangerous actions** — force push, deleting root, exposing secrets
@@ -58,7 +59,7 @@ Set via environment variables or `~/.safeclaw/config.json`:
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `SAFECLAW_URL` | `http://localhost:8420/api/v1` | SafeClaw service URL |
+| `SAFECLAW_URL` | `https://api.safeclaw.eu/api/v1` | SafeClaw service URL |
 | `SAFECLAW_API_KEY` | *(empty)* | API key for cloud mode |
 | `SAFECLAW_TIMEOUT_MS` | `500` | Request timeout in ms |
 | `SAFECLAW_ENABLED` | `true` | Set `false` to disable |

package/SKILL.md

@@ -12,26 +12,15 @@ SafeClaw adds ontology-based constraint checking to your OpenClaw agent. Every t
 
 ## Setup
 
-### Option A: Local mode (self-hosted)
+The plugin connects to `https://api.safeclaw.eu/api/v1` by default — no configuration needed.
 
-```bash
-# 1. Start the SafeClaw service
-pip install safeclaw
-safeclaw init
-uvicorn safeclaw.main:app --port 8420
-
-# 2. Install this plugin (done if you're reading this via clawhub)
-# The plugin auto-connects to http://localhost:8420
-```
+### Self-hosted mode
 
-### Option B: Cloud mode (safeclaw.eu)
+To run your own SafeClaw service, override the URL:
 
 ```bash
-# 1. Sign up at safeclaw.eu and get your API key
-
-# 2. Set your API key
-export SAFECLAW_URL="https://api.safeclaw.eu/api/v1"
-export SAFECLAW_API_KEY="sc_live_your_key_here"
+export SAFECLAW_URL="http://localhost:8420/api/v1"
+export SAFECLAW_API_KEY="sc_live_your_key_here"  # optional
 ```
 
 ## Configuration
@@ -40,7 +29,7 @@ Set via environment variables or `~/.safeclaw/config.json`:
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `SAFECLAW_URL` | `http://localhost:8420/api/v1` | SafeClaw service URL |
+| `SAFECLAW_URL` | `https://api.safeclaw.eu/api/v1` | SafeClaw service URL |
 | `SAFECLAW_API_KEY` | (empty) | API key for remote/cloud mode |
 | `SAFECLAW_TIMEOUT_MS` | `500` | Request timeout in milliseconds |
 | `SAFECLAW_ENABLED` | `true` | Set to `false` to disable |

package/dist/index.js

@@ -11,7 +11,7 @@ import { join } from 'path';
 import { homedir } from 'os';
 function loadConfig() {
     const defaults = {
-        serviceUrl: process.env.SAFECLAW_URL ?? 'http://localhost:8420/api/v1',
+        serviceUrl: process.env.SAFECLAW_URL ?? 'https://api.safeclaw.eu/api/v1',
         apiKey: process.env.SAFECLAW_API_KEY ?? '',
         timeoutMs: parseInt(process.env.SAFECLAW_TIMEOUT_MS ?? '500', 10),
         enabled: process.env.SAFECLAW_ENABLED !== 'false',
@@ -77,28 +77,70 @@ async function post(path, body) {
             signal: AbortSignal.timeout(config.timeoutMs),
         });
         if (!res.ok) {
-            console.warn(`[SafeClaw] HTTP ${res.status} from ${path}`);
+            // Try to parse structured error body from service
+            try {
+                const errBody = await res.json();
+                const detail = errBody.detail ?? `HTTP ${res.status}`;
+                const hint = errBody.hint ? ` (${errBody.hint})` : '';
+                console.warn(`[SafeClaw] ${path}: ${detail}${hint}`);
+            }
+            catch {
+                console.warn(`[SafeClaw] HTTP ${res.status} from ${path}`);
+            }
             return null; // Caller checks failMode
         }
         return await res.json();
     }
     catch (e) {
         if (e instanceof DOMException && e.name === 'TimeoutError') {
-            console.debug(`[SafeClaw] Timeout on ${path}`);
+            console.warn(`[SafeClaw] Timeout after ${config.timeoutMs}ms on ${path} (${config.serviceUrl})`);
+        }
+        else if (e instanceof TypeError && (e.message.includes('fetch') || e.message.includes('ECONNREFUSED'))) {
+            console.warn(`[SafeClaw] Connection refused: ${config.serviceUrl}${path} — is the service running?`);
         }
         else {
-            console.debug(`[SafeClaw] Service unavailable: ${path}`);
+            console.warn(`[SafeClaw] Service unavailable: ${config.serviceUrl}${path}`);
         }
         return null; // Caller checks failMode
     }
 }
+async function checkConnection() {
+    const label = `[SafeClaw]`;
+    console.log(`${label} Connecting to ${config.serviceUrl} ...`);
+    console.log(`${label} Mode: enforcement=${config.enforcement}, failMode=${config.failMode}`);
+    try {
+        const res = await fetch(`${config.serviceUrl}/health`, {
+            signal: AbortSignal.timeout(config.timeoutMs * 2),
+        });
+        if (res.ok) {
+            const data = await res.json();
+            console.log(`${label} ✓ Connected — service ${data.status ?? 'ok'}`);
+        }
+        else {
+            console.warn(`${label} ✗ Service responded with HTTP ${res.status}`);
+        }
+    }
+    catch {
+        console.warn(`${label} ✗ Cannot reach service at ${config.serviceUrl}`);
+        if (config.failMode === 'closed') {
+            console.warn(`${label}   fail-mode=closed → tool calls will be BLOCKED until service is reachable`);
+        }
+        else {
+            console.warn(`${label}   fail-mode=open → tool calls will be ALLOWED despite no connection`);
+        }
+    }
+}
 export default {
     id: 'openclaw-safeclaw-plugin',
     name: 'SafeClaw Neurosymbolic Governance',
-    version: '0.1.0',
+    version: '0.1.2',
     register(api) {
-        if (!config.enabled)
+        if (!config.enabled) {
+            console.log('[SafeClaw] Plugin disabled');
             return;
+        }
+        // Fire-and-forget startup health check
+        checkConnection().catch(() => { });
         // THE GATE — constraint checking on every tool call
         api.on('before_tool_call', async (event, ctx) => {
             const r = await post('/evaluate/tool-call', {
@@ -109,10 +151,10 @@ export default {
                 sessionHistory: event.sessionHistory ?? [],
             });
             if (r === null && config.failMode === 'closed' && config.enforcement === 'enforce') {
-                return { block: true, blockReason: 'SafeClaw service unavailable (fail-closed)' };
+                return { block: true, blockReason: `SafeClaw service unavailable at ${config.serviceUrl} (fail-closed)` };
             }
             else if (r === null && config.failMode === 'closed' && config.enforcement === 'warn-only') {
-                console.warn('[SafeClaw] Service unavailable (fail-closed mode, warn-only)');
+                console.warn(`[SafeClaw] Service unavailable at ${config.serviceUrl} (fail-closed mode, warn-only)`);
             }
             if (r?.block) {
                 if (config.enforcement === 'enforce') {

package/index.ts

@@ -26,7 +26,7 @@ interface SafeClawPluginConfig {
 
 function loadConfig(): SafeClawPluginConfig {
   const defaults: SafeClawPluginConfig = {
-    serviceUrl: process.env.SAFECLAW_URL ?? 'http://localhost:8420/api/v1',
+    serviceUrl: process.env.SAFECLAW_URL ?? 'https://api.safeclaw.eu/api/v1',
     apiKey: process.env.SAFECLAW_API_KEY ?? '',
     timeoutMs: parseInt(process.env.SAFECLAW_TIMEOUT_MS ?? '500', 10),
     enabled: process.env.SAFECLAW_ENABLED !== 'false',
@@ -93,15 +93,25 @@ async function post(path: string, body: Record<string, unknown>): Promise<Record
       signal: AbortSignal.timeout(config.timeoutMs),
     });
     if (!res.ok) {
-      console.warn(`[SafeClaw] HTTP ${res.status} from ${path}`);
+      // Try to parse structured error body from service
+      try {
+        const errBody = await res.json() as Record<string, unknown>;
+        const detail = errBody.detail ?? `HTTP ${res.status}`;
+        const hint = errBody.hint ? ` (${errBody.hint})` : '';
+        console.warn(`[SafeClaw] ${path}: ${detail}${hint}`);
+      } catch {
+        console.warn(`[SafeClaw] HTTP ${res.status} from ${path}`);
+      }
       return null;  // Caller checks failMode
     }
     return await res.json() as Record<string, unknown>;
   } catch (e) {
     if (e instanceof DOMException && e.name === 'TimeoutError') {
-      console.debug(`[SafeClaw] Timeout on ${path}`);
+      console.warn(`[SafeClaw] Timeout after ${config.timeoutMs}ms on ${path} (${config.serviceUrl})`);
+    } else if (e instanceof TypeError && (e.message.includes('fetch') || e.message.includes('ECONNREFUSED'))) {
+      console.warn(`[SafeClaw] Connection refused: ${config.serviceUrl}${path} — is the service running?`);
     } else {
-      console.debug(`[SafeClaw] Service unavailable: ${path}`);
+      console.warn(`[SafeClaw] Service unavailable: ${config.serviceUrl}${path}`);
     }
     return null;  // Caller checks failMode
   }
@@ -129,13 +139,44 @@ interface PluginApi {
   ): void;
 }
 
+async function checkConnection(): Promise<void> {
+  const label = `[SafeClaw]`;
+  console.log(`${label} Connecting to ${config.serviceUrl} ...`);
+  console.log(`${label} Mode: enforcement=${config.enforcement}, failMode=${config.failMode}`);
+
+  try {
+    const res = await fetch(`${config.serviceUrl}/health`, {
+      signal: AbortSignal.timeout(config.timeoutMs * 2),
+    });
+    if (res.ok) {
+      const data = await res.json() as Record<string, unknown>;
+      console.log(`${label} ✓ Connected — service ${data.status ?? 'ok'}`);
+    } else {
+      console.warn(`${label} ✗ Service responded with HTTP ${res.status}`);
+    }
+  } catch {
+    console.warn(`${label} ✗ Cannot reach service at ${config.serviceUrl}`);
+    if (config.failMode === 'closed') {
+      console.warn(`${label}   fail-mode=closed → tool calls will be BLOCKED until service is reachable`);
+    } else {
+      console.warn(`${label}   fail-mode=open → tool calls will be ALLOWED despite no connection`);
+    }
+  }
+}
+
 export default {
   id: 'openclaw-safeclaw-plugin',
   name: 'SafeClaw Neurosymbolic Governance',
-  version: '0.1.0',
+  version: '0.1.2',
 
   register(api: PluginApi) {
-    if (!config.enabled) return;
+    if (!config.enabled) {
+      console.log('[SafeClaw] Plugin disabled');
+      return;
+    }
+
+    // Fire-and-forget startup health check
+    checkConnection().catch(() => {});
 
     // THE GATE — constraint checking on every tool call
     api.on('before_tool_call', async (event: PluginEvent, ctx: PluginContext) => {
@@ -148,9 +189,9 @@ export default {
       });
 
       if (r === null && config.failMode === 'closed' && config.enforcement === 'enforce') {
-        return { block: true, blockReason: 'SafeClaw service unavailable (fail-closed)' };
+        return { block: true, blockReason: `SafeClaw service unavailable at ${config.serviceUrl} (fail-closed)` };
       } else if (r === null && config.failMode === 'closed' && config.enforcement === 'warn-only') {
-        console.warn('[SafeClaw] Service unavailable (fail-closed mode, warn-only)');
+        console.warn(`[SafeClaw] Service unavailable at ${config.serviceUrl} (fail-closed mode, warn-only)`);
       }
       if (r?.block) {
         if (config.enforcement === 'enforce') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-safeclaw-plugin",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "SafeClaw Neurosymbolic Governance plugin for OpenClaw — validates AI agent actions against OWL ontologies and SHACL constraints",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",