@moltnet/guard 1.0.0

package/README.md

@@ -0,0 +1,122 @@
+# @moltnet/guard
+
+**MoltGuard plugin for Clawdbot** — Security & observability for AI agents.
+
+[![MoltGuard](https://guard.moltnet.ai/api/badge?label=moltguard&status=secure)](https://guard.moltnet.ai)
+
+## Features
+
+- 🔍 **Action Logging** — Every tool call is logged with risk classification
+- 🧠 **Mind Graph** — Visualize your agent's thought process in real-time
+- ✋ **Intent Gating** — Require approval for high-risk actions
+- 🎮 **Remote Control** — Pause, resume, or stop your agent remotely
+- 📊 **Audit Dashboard** — Complete history with search, filters, and export
+
+## Installation
+
+```bash
+clawdbot plugins install @moltnet/guard
+```
+
+## Configuration
+
+1. **Get your token** at [guard.moltnet.ai](https://guard.moltnet.ai)
+
+2. **Add to your Clawdbot config** (`~/.clawdbot/config.json`):
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "moltguard": {
+        "enabled": true,
+        "config": {
+          "token": "mg_your_token_here",
+          "agentName": "my-assistant"
+        }
+      }
+    }
+  }
+}
+```
+
+3. **Restart Clawdbot**
+
+```bash
+clawdbot gateway restart
+```
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `token` | string | **required** | Your MoltGuard API token |
+| `url` | string | `https://guard.moltnet.ai` | MoltGuard server URL |
+| `agentName` | string | `clawdbot-<hostname>` | Display name in dashboard |
+| `logThoughts` | boolean | `true` | Send reasoning traces to Mind Graph |
+| `gateHighRisk` | boolean | `true` | Require approval for high-risk actions |
+| `gateTools` | string[] | `["exec", "message", "write"]` | Tools that require approval |
+| `pollCommands` | boolean | `true` | Enable remote control (pause/resume/stop) |
+| `pollIntervalMs` | number | `5000` | Command poll interval in ms |
+
+## Risk Classification
+
+The plugin automatically classifies tool calls by risk:
+
+| Risk | Tools |
+|------|-------|
+| 🔴 **Critical** | `gateway`, `exec` (with `rm`, `sudo`) |
+| 🟠 **High** | `exec`, `message`, `nodes` |
+| 🟡 **Medium** | `write`, `edit`, `browser`, `cron`, `process` |
+| 🟢 **Low** | `read`, `web_search`, `web_fetch`, `memory_*` |
+
+## How It Works
+
+```
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│    Clawdbot     │────▶│   MoltGuard     │◀────│     Human       │
+│    (Agent)      │     │   Plugin        │     │   (Dashboard)   │
+└─────────────────┘     └────────┬────────┘     └─────────────────┘
+                                 │
+                                 ▼
+                        ┌─────────────────┐
+                        │  guard.moltnet  │
+                        │     .ai         │
+                        └─────────────────┘
+```
+
+1. Plugin intercepts all tool calls via `tool_result_persist` hook
+2. Actions are logged to MoltGuard with risk classification
+3. High-risk actions wait for approval (if `gateHighRisk` enabled)
+4. Human approves/rejects from dashboard or Telegram
+5. Plugin polls for remote control commands
+
+## Self-Hosting
+
+If you're running your own MoltGuard instance:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "moltguard": {
+        "enabled": true,
+        "config": {
+          "url": "https://your-moltguard.com",
+          "token": "your_token"
+        }
+      }
+    }
+  }
+}
+```
+
+## Links
+
+- **Dashboard:** [guard.moltnet.ai](https://guard.moltnet.ai)
+- **Docs:** [guard.moltnet.ai/docs](https://guard.moltnet.ai/docs)
+- **GitHub:** [github.com/moltnet/guard](https://github.com/moltnet/guard)
+
+## License
+
+MIT

package/clawdbot.plugin.json

@@ -0,0 +1,65 @@
+{
+  "id": "moltguard",
+  "name": "MoltGuard",
+  "version": "1.0.0",
+  "description": "Security & observability for AI agents. See what your agent is thinking, approve risky actions, control it remotely.",
+  "homepage": "https://guard.moltnet.ai",
+  "author": "MoltNet <hello@moltnet.ai>",
+  "license": "MIT",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "url": {
+        "type": "string",
+        "default": "https://guard.moltnet.ai",
+        "description": "MoltGuard server URL"
+      },
+      "token": {
+        "type": "string",
+        "description": "Your MoltGuard API token (get one at guard.moltnet.ai)"
+      },
+      "agentName": {
+        "type": "string",
+        "description": "Display name for this agent in MoltGuard dashboard"
+      },
+      "logThoughts": {
+        "type": "boolean",
+        "default": true,
+        "description": "Send reasoning traces to Mind Graph"
+      },
+      "gateHighRisk": {
+        "type": "boolean",
+        "default": true,
+        "description": "Require approval for high-risk actions"
+      },
+      "gateTools": {
+        "type": "array",
+        "items": { "type": "string" },
+        "default": ["exec", "message", "write"],
+        "description": "Tool names that require approval when gateHighRisk is enabled"
+      },
+      "pollCommands": {
+        "type": "boolean",
+        "default": true,
+        "description": "Poll for remote control commands (pause/resume/stop)"
+      },
+      "pollIntervalMs": {
+        "type": "number",
+        "default": 5000,
+        "description": "How often to poll for commands (ms)"
+      }
+    },
+    "required": ["token"]
+  },
+  "uiHints": {
+    "url": { "label": "MoltGuard URL", "placeholder": "https://guard.moltnet.ai" },
+    "token": { "label": "API Token", "sensitive": true, "placeholder": "mg_xxxxxxxxxxxx" },
+    "agentName": { "label": "Agent Name", "placeholder": "my-assistant" },
+    "logThoughts": { "label": "Log Thoughts to Mind Graph" },
+    "gateHighRisk": { "label": "Gate High-Risk Actions" },
+    "gateTools": { "label": "Tools Requiring Approval" },
+    "pollCommands": { "label": "Enable Remote Control" },
+    "pollIntervalMs": { "label": "Poll Interval (ms)" }
+  }
+}

package/index.ts

@@ -0,0 +1,338 @@
+/**
+ * MoltGuard Plugin for Clawdbot
+ * 
+ * Security & observability for AI agents.
+ * - Logs all tool calls to MoltGuard
+ * - Sends reasoning traces to Mind Graph
+ * - Gates high-risk actions (requires approval)
+ * - Polls for remote control commands
+ */
+
+import type { PluginAPI, PluginRegisterFn } from 'clawdbot';
+
+interface MoltGuardConfig {
+  url: string;
+  token: string;
+  agentName?: string;
+  logThoughts?: boolean;
+  gateHighRisk?: boolean;
+  gateTools?: string[];
+  pollCommands?: boolean;
+  pollIntervalMs?: number;
+}
+
+interface MoltGuardState {
+  agentId: string | null;
+  sessionId: string | null;
+  paused: boolean;
+  pollInterval: NodeJS.Timeout | null;
+}
+
+const state: MoltGuardState = {
+  agentId: null,
+  sessionId: null,
+  paused: false,
+  pollInterval: null,
+};
+
+// Risk classification for common tools
+const TOOL_RISK: Record<string, 'low' | 'medium' | 'high' | 'critical'> = {
+  // High risk - external effects
+  'exec': 'high',
+  'message': 'high',
+  'write': 'medium',
+  'edit': 'medium',
+  'browser': 'medium',
+  'web_fetch': 'low',
+  'web_search': 'low',
+  'read': 'low',
+  'memory_search': 'low',
+  'memory_get': 'low',
+  'tts': 'low',
+  'image': 'low',
+  // Critical - system changes
+  'gateway': 'critical',
+  'cron': 'medium',
+  'nodes': 'high',
+  'canvas': 'low',
+  'process': 'medium',
+  'sessions_spawn': 'medium',
+  'sessions_send': 'medium',
+};
+
+async function apiCall(
+  config: MoltGuardConfig,
+  endpoint: string,
+  method: 'GET' | 'POST' | 'PATCH' = 'POST',
+  body?: Record<string, unknown>
+): Promise<unknown> {
+  const url = `${config.url}/api${endpoint}`;
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+    'X-API-Key': config.token,
+  };
+
+  const res = await fetch(url, {
+    method,
+    headers,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`MoltGuard API error: ${res.status} ${text}`);
+  }
+
+  return res.json();
+}
+
+async function registerAgent(config: MoltGuardConfig): Promise<string> {
+  const hostname = process.env.HOSTNAME || 'unknown';
+  const result = await apiCall(config, '/agents/register', 'POST', {
+    name: config.agentName || `clawdbot-${hostname}`,
+    description: `Clawdbot agent on ${hostname}`,
+    capabilities: ['tool_execution', 'reasoning', 'memory'],
+  }) as { id: string };
+  return result.id;
+}
+
+async function startSession(config: MoltGuardConfig, agentName: string): Promise<string> {
+  const result = await apiCall(config, '/sessions', 'POST', {
+    agent: agentName,
+    metadata: JSON.stringify({ startedAt: new Date().toISOString() }),
+  }) as { id: string };
+  return result.id;
+}
+
+async function logTrace(
+  config: MoltGuardConfig,
+  agentName: string,
+  sessionId: string | null,
+  type: string,
+  title: string,
+  content: string
+): Promise<void> {
+  await apiCall(config, '/traces', 'POST', {
+    agent: agentName,
+    sessionId,
+    type,
+    title,
+    content,
+  });
+}
+
+async function logAction(
+  config: MoltGuardConfig,
+  agentName: string,
+  sessionId: string | null,
+  toolName: string,
+  params: Record<string, unknown>,
+  risk: string,
+  status: 'pending' | 'executed' = 'executed'
+): Promise<{ id: string; status: string }> {
+  const result = await apiCall(config, '/actions', 'POST', {
+    agent: agentName,
+    sessionId,
+    type: `tool.${toolName}`,
+    description: summarizeToolCall(toolName, params),
+    details: JSON.stringify(params),
+    risk,
+    status,
+    reversible: toolName === 'write' || toolName === 'edit' ? 1 : 0,
+  }) as { id: string; status: string };
+  return result;
+}
+
+async function pollForDecision(
+  config: MoltGuardConfig,
+  actionId: string,
+  timeoutMs: number = 300000
+): Promise<'approved' | 'rejected' | 'timeout'> {
+  const startTime = Date.now();
+  const pollInterval = 2000;
+
+  while (Date.now() - startTime < timeoutMs) {
+    const result = await apiCall(config, `/actions/${actionId}/decision`, 'GET') as { status: string };
+    
+    if (result.status === 'approved') return 'approved';
+    if (result.status === 'rejected' || result.status === 'timeout') return result.status as 'rejected' | 'timeout';
+    
+    await new Promise(resolve => setTimeout(resolve, pollInterval));
+  }
+
+  return 'timeout';
+}
+
+async function pollCommands(config: MoltGuardConfig, agentName: string): Promise<void> {
+  try {
+    const commands = await apiCall(config, `/control/${agentName}/pending`, 'GET') as Array<{
+      id: string;
+      command: string;
+      params?: string;
+    }>;
+
+    for (const cmd of commands) {
+      console.log(`[moltguard] Received command: ${cmd.command}`);
+      
+      switch (cmd.command) {
+        case 'pause':
+          state.paused = true;
+          console.log('[moltguard] Agent PAUSED by remote control');
+          break;
+        case 'resume':
+          state.paused = false;
+          console.log('[moltguard] Agent RESUMED by remote control');
+          break;
+        case 'stop':
+          console.log('[moltguard] Agent STOPPED by remote control');
+          process.exit(0);
+          break;
+      }
+
+      // ACK the command
+      await apiCall(config, `/control/${agentName}/ack/${cmd.id}`, 'POST');
+    }
+  } catch (err) {
+    // Silent fail for polling
+  }
+}
+
+function summarizeToolCall(toolName: string, params: Record<string, unknown>): string {
+  switch (toolName) {
+    case 'exec':
+      return `Execute: ${String(params.command || '').slice(0, 100)}`;
+    case 'write':
+      return `Write file: ${params.path || params.file_path}`;
+    case 'edit':
+      return `Edit file: ${params.path || params.file_path}`;
+    case 'read':
+      return `Read file: ${params.path || params.file_path}`;
+    case 'message':
+      return `Send message: ${String(params.message || '').slice(0, 50)}...`;
+    case 'browser':
+      return `Browser: ${params.action} ${params.targetUrl || ''}`;
+    case 'web_fetch':
+      return `Fetch URL: ${params.url}`;
+    case 'web_search':
+      return `Search: ${params.query}`;
+    case 'gateway':
+      return `Gateway: ${params.action}`;
+    case 'cron':
+      return `Cron: ${params.action}`;
+    default:
+      return `${toolName}: ${JSON.stringify(params).slice(0, 80)}`;
+  }
+}
+
+function getToolRisk(toolName: string, params: Record<string, unknown>): 'low' | 'medium' | 'high' | 'critical' {
+  const baseRisk = TOOL_RISK[toolName] || 'medium';
+  
+  // Elevate risk for certain patterns
+  if (toolName === 'exec') {
+    const cmd = String(params.command || '').toLowerCase();
+    if (cmd.includes('rm ') || cmd.includes('sudo') || cmd.includes('chmod')) {
+      return 'critical';
+    }
+    if (cmd.includes('curl') || cmd.includes('wget') || cmd.includes('ssh')) {
+      return 'high';
+    }
+  }
+  
+  if (toolName === 'write' || toolName === 'edit') {
+    const path = String(params.path || params.file_path || '');
+    if (path.includes('.ssh') || path.includes('.env') || path.includes('config')) {
+      return 'high';
+    }
+  }
+
+  return baseRisk;
+}
+
+const register: PluginRegisterFn = (api: PluginAPI) => {
+  const config = api.config.plugins?.entries?.moltguard?.config as MoltGuardConfig | undefined;
+  
+  if (!config?.token) {
+    console.log('[moltguard] No token configured. Get one at https://guard.moltnet.ai');
+    return;
+  }
+
+  const cfg: MoltGuardConfig = {
+    url: config.url || 'https://guard.moltnet.ai',
+    token: config.token,
+    agentName: config.agentName,
+    logThoughts: config.logThoughts ?? true,
+    gateHighRisk: config.gateHighRisk ?? true,
+    gateTools: config.gateTools ?? ['exec', 'message', 'write'],
+    pollCommands: config.pollCommands ?? true,
+    pollIntervalMs: config.pollIntervalMs ?? 5000,
+  };
+
+  const agentName = cfg.agentName || `clawdbot-${process.env.HOSTNAME || 'agent'}`;
+
+  // Register agent on startup
+  (async () => {
+    try {
+      state.agentId = await registerAgent(cfg);
+      state.sessionId = await startSession(cfg, agentName);
+      console.log(`[moltguard] Connected to ${cfg.url}`);
+      console.log(`[moltguard] Agent: ${agentName} | Session: ${state.sessionId}`);
+
+      // Start command polling
+      if (cfg.pollCommands) {
+        state.pollInterval = setInterval(() => {
+          pollCommands(cfg, agentName);
+        }, cfg.pollIntervalMs);
+      }
+    } catch (err) {
+      console.error('[moltguard] Failed to connect:', err instanceof Error ? err.message : String(err));
+    }
+  })();
+
+  // Hook: Intercept tool results before persistence
+  api.hooks?.register('tool_result_persist', (toolResult) => {
+    if (!toolResult || typeof toolResult !== 'object') return toolResult;
+
+    const { name, input } = toolResult as { name?: string; input?: Record<string, unknown> };
+    if (!name) return toolResult;
+
+    const risk = getToolRisk(name, input || {});
+    const shouldGate = cfg.gateHighRisk && 
+      (risk === 'high' || risk === 'critical') && 
+      cfg.gateTools?.includes(name);
+
+    // Log the action (async, don't block)
+    logAction(cfg, agentName, state.sessionId, name, input || {}, risk, shouldGate ? 'pending' : 'executed')
+      .catch(err => console.error('[moltguard] Failed to log action:', err));
+
+    return toolResult;
+  });
+
+  // Hook: Log agent bootstrap (session start)
+  api.hooks?.register('agent:bootstrap', (event) => {
+    if (cfg.logThoughts) {
+      logTrace(cfg, agentName, state.sessionId, 'session', 'Session Started', 'Agent bootstrap initiated')
+        .catch(() => {});
+    }
+  });
+
+  // Hook: Log commands
+  api.hooks?.register('command', (event) => {
+    if (cfg.logThoughts && event.action) {
+      logTrace(cfg, agentName, state.sessionId, 'command', `Command: /${event.action}`, `User issued /${event.action}`)
+        .catch(() => {});
+    }
+  });
+
+  // Cleanup on exit
+  process.on('beforeExit', () => {
+    if (state.pollInterval) {
+      clearInterval(state.pollInterval);
+    }
+  });
+
+  console.log('[moltguard] Plugin loaded');
+};
+
+export default register;
+export const id = 'moltguard';
+export const name = 'MoltGuard';

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@moltnet/guard",
+  "version": "1.0.0",
+  "description": "MoltGuard plugin for Clawdbot - Security & observability for AI agents",
+  "main": "index.ts",
+  "type": "module",
+  "author": "MoltNet <hello@moltnet.ai>",
+  "license": "MIT",
+  "homepage": "https://guard.moltnet.ai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/moltnet/guard"
+  },
+  "keywords": [
+    "clawdbot",
+    "clawdbot-plugin",
+    "ai-agent",
+    "security",
+    "observability",
+    "audit",
+    "moltguard"
+  ],
+  "clawdbot": {
+    "extensions": ["./index.ts"]
+  },
+  "peerDependencies": {
+    "clawdbot": ">=0.1.0"
+  },
+  "files": [
+    "index.ts",
+    "clawdbot.plugin.json",
+    "README.md"
+  ]
+}