@inquiryon/amp-governance 1.1.4 → 1.1.6

package/index.js

@@ -1,4 +1,5 @@
 import * as fs from 'fs';
+import { normalizeTool } from './toolNormalization.js';
 
 console.log('[AMP Governance] Plugin module loaded — Phase 4.');
 
@@ -55,6 +56,11 @@ let _lastSender = null;  // { from: string, channelId: string }
 // Set by register() so notifyUser can use the runtime API directly
 let _runtime = null;
 
+// AMP reachability state — flips to false when a real AMP call fails,
+// back to true the next time a real AMP call succeeds.
+let _ampReachable = true;
+let _ampDownNotified = false; // prevent notification spam while AMP is down
+
 // ── HOOK AUTO-DEPLOY ─────────────────────────────────────────────────────────
 
 /**
@@ -151,6 +157,7 @@ async function ensureInstance() {
       _instanceId = id;
       writeSession(id);
       console.log(`[AMP Governance] AMP instance created: ${id}`);
+      await notifyAmpRecovered();
     }
     return _instanceId || null;
   } catch (err) {
@@ -159,6 +166,7 @@ async function ensureInstance() {
     let target = '';
     try { target = buildAmpUrl('/api/agent/init'); } catch (_) {}
     console.error(`[AMP Governance] ensureInstance failed: ${em}${ec ? ` | cause=${ec}` : ''}${target ? ` | url=${target}` : ''}`);
+    _ampReachable = false;
     return null;
   }
 }
@@ -199,12 +207,60 @@ async function notifyUser(sender, message) {
   const prefixed = `[AMP]\n${message}`;
   console.log(`[AMP Governance] Sending notification to ${sender.from}: ${message}`);
   try {
-    await _runtime.channel.whatsapp.sendMessageWhatsApp(sender.from, prefixed, { verbose: false });
+    const channelId = sender.channelId || '';
+    if (channelId === 'slack' || sender.from.startsWith('slack:')) {
+      // Strip the 'slack:' prefix — sendMessageSlack expects 'channel:<id>' or 'user:<id>', not 'slack:channel:<id>'
+      const slackTarget = sender.from.startsWith('slack:') ? sender.from.slice('slack:'.length) : sender.from;
+      await _runtime.channel.slack.sendMessageSlack(slackTarget, prefixed);
+    } else {
+      await _runtime.channel.whatsapp.sendMessageWhatsApp(sender.from, prefixed, { verbose: false });
+    }
   } catch (err) {
     console.warn('[AMP Governance] notifyUser failed:', err.message);
   }
 }
 
+/**
+ * Called whenever a real AMP call fails (init or hitl/request).
+ * Sends a clear channel notification on the first occurrence, then stays quiet
+ * until AMP recovers (to avoid flooding the user with repeated messages).
+ */
+async function notifyAmpDown(tool, errDetail) {
+  const ampUrl = (() => { try { return buildAmpUrl('/'); } catch (_) { return config?.AMP_BACKEND_URL || 'unknown'; } })();
+
+  if (!_ampDownNotified) {
+    _ampDownNotified = true;
+    const msg =
+      `🚨 *AMP Governance Service Unreachable*\n\n` +
+      `OpenClaw cannot connect to the AMP Governance service at:\n${ampUrl}\n\n` +
+      `*All agent activities are now blocked* until AMP is back online. ` +
+      `This is a safety measure — no tools (file reads, shell commands, web searches, etc.) ` +
+      `will be executed while governance is unavailable.\n\n` +
+      `*What to do:*\n` +
+      `• Verify the AMP backend is running (check pm2 or your server)\n` +
+      `• Confirm the AMP_BACKEND_URL in your amp_config.json is correct\n` +
+      `• Once AMP is restored, send your request again and OpenClaw will resume normally\n\n` +
+      `_Technical detail: ${errDetail}_`;
+    await notifyUser(_lastSender, msg);
+    console.error(`[AMP Governance] AMP unreachable — all tool calls blocked. URL: ${ampUrl} | Error: ${errDetail}`);
+  }
+}
+
+/**
+ * Called when a real AMP call succeeds after a period of being down.
+ * Clears the down state so the next failure notifies again.
+ */
+async function notifyAmpRecovered() {
+  if (!_ampReachable) {
+    _ampReachable    = true;
+    _ampDownNotified = false;
+    await notifyUser(_lastSender,
+      `✅ *AMP Governance Service Restored*\n\nThe AMP Governance service is back online. OpenClaw is resuming normal operation — your next request will be processed.`
+    );
+    console.log('[AMP Governance] AMP service recovered — resuming normal operation.');
+  }
+}
+
 // ── HITL POLICY ENGINE ───────────────────────────────────────────────────────
 
 /**
@@ -213,6 +269,7 @@ async function notifyUser(sender, message) {
  */
 async function requestHitlEval(instanceId, tool, params) {
   const apiKey = getAmpApiKey();
+  const { tool: normTool, action: normAction } = normalizeTool(tool, params);
   const res = await fetch(buildAmpUrl('/api/hitl/request'), {
     method: 'POST',
     headers: { 'X-API-Key': apiKey, 'Content-Type': 'application/json' },
@@ -221,8 +278,8 @@ async function requestHitlEval(instanceId, tool, params) {
       instance_id: instanceId,
       org_id:     config.AMP_ORG_ID,
       agent_name: config.AGENT_NAME,
-      tool,
-      action:     params?.action || '*',
+      tool:       normTool,
+      action:     normAction,
       context:    params || {},
       hitl: {
         enable: true,
@@ -275,10 +332,15 @@ async function checkToolPolicy(instanceId, tool, params) {
   let hitlResponse;
   try {
     hitlResponse = await requestHitlEval(instanceId, tool, params);
+    // Successful contact with AMP — clear any prior down state
+    await notifyAmpRecovered();
   } catch (err) {
-    console.warn(`[AMP Governance] HITL request failed (fail open): ${err.message}`);
-    await ampLog(instanceId, `AMP governance check failed (fail open): ${err.message}`, 'WARN');
-    return {};
+    const em = err && err.message ? err.message : String(err);
+    console.error(`[AMP Governance] HITL request failed — blocking tool "${tool}": ${em}`);
+    await ampLog(instanceId, `AMP governance check failed — tool "${tool}" blocked: ${em}`, 'ERROR');
+    _ampReachable = false;
+    await notifyAmpDown(tool, em);
+    return { block: true, blockReason: `AMP Governance service is unreachable. Tool "${tool}" was blocked as a safety measure. Restore the AMP backend and retry.` };
   }
 
   const status = hitlResponse.status;
@@ -473,8 +535,8 @@ export default {
       _instanceId = null;
     });
 
-    // ── INBOUND MESSAGE: cache sender for HITL notifications ─────────────────
-    api.on('message_received', (event, ctx) => {
+    // ── INBOUND MESSAGE: cache sender for HITL/outage notifications ──────────
+    api.on('message_received', async (event, ctx) => {
       if (event.from && ctx.channelId) {
         _lastSender = { from: event.from, channelId: ctx.channelId };
         console.log(`[AMP Governance] Sender cached: ${event.from} on ${ctx.channelId}`);
@@ -488,8 +550,22 @@ export default {
 
       const instanceId = await ensureInstance();
       if (!instanceId) {
-        console.warn('[AMP Governance] No instance available — skipping governance check.');
-        return {};
+        const reason = !config
+          ? 'AMP Governance plugin is not configured (amp_config.json missing or invalid).'
+          : 'AMP Governance service is unreachable.';
+        console.error(`[AMP Governance] No instance available — blocking tool "${tool}". Reason: ${reason}`);
+        if (!config) {
+          await notifyUser(_lastSender,
+            `🚨 *AMP Governance Not Configured*\n\n` +
+            `The AMP Governance plugin has no valid configuration. ` +
+            `All OpenClaw activities are blocked until amp_config.json is set up correctly.\n\n` +
+            `Please configure AMP_BACKEND_URL, AMP_API_KEY, and AMP_ORG_ID in:\n` +
+            `~/.openclaw/hooks/amp/amp_config.json`
+          );
+        } else {
+          await notifyAmpDown(tool, 'Could not establish an AMP session — backend may be down or unreachable.');
+        }
+        return { block: true, blockReason: reason };
       }
 
       // Log the incoming tool call

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@inquiryon/amp-governance",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "description": "AMP governance plugin for OpenClaw",
   "type": "module",
   "files": [
     "index.js",
+    "toolNormalization.js",
     "openclaw.plugin.json",
     "hook/handler.ts",
     "hook/HOOK.md",

package/toolNormalization.js

@@ -0,0 +1,26 @@
+// Normalizes OpenClaw's raw tool names into the same tool/action vocabulary
+// used by AMP's Hermes plugin (AHP's policy.py), so a single AMP policy can
+// govern both agent types identically instead of matching on each agent's
+// own raw tool names.
+
+const TOOL_MAP = {
+  web_search: { tool: 'exec', action: 'web_search' },
+  read:       { tool: 'read', action: 'read' },
+  write:      { tool: 'write', action: 'write' },
+  edit:       { tool: 'write', action: 'edit' },
+  bash:       { tool: 'exec', action: 'exec' },
+  shell:      { tool: 'exec', action: 'exec' },
+};
+
+/**
+ * Returns { tool, action } for a raw OpenClaw tool name.
+ * Unlike Hermes's normalizer (which returns null for anything outside its
+ * known set), unmapped tools fall back to the raw name with action '*' —
+ * so a not-yet-mapped OpenClaw tool still reaches AMP instead of being
+ * silently dropped.
+ */
+export function normalizeTool(rawTool, params) {
+  const mapped = TOOL_MAP[rawTool];
+  if (mapped) return { tool: mapped.tool, action: mapped.action };
+  return { tool: rawTool, action: params?.action || '*' };
+}