@inquiryon/openclaw-amp-governance 1.0.1 → 1.0.4

package/index.js

@@ -1,16 +1,412 @@
-console.log('[AMP Governance] Plugin module loaded.');
+import * as fs from 'fs';
+
+console.log('[AMP Governance] Plugin module loaded — Phase 4.');
+
+const SESSION_FILE = '/tmp/amp-session-state.json';
+const CONFIG_FILE = `${process.env.HOME}/.openclaw/hooks/amp/amp_config.json`;
+
+// Tools that are internal/noisy — skip logging and policy checks
+const SKIP_TOOLS = new Set(['session_status', 'heartbeat']);
+
+// HITL polling config
+const HITL_POLL_INTERVAL_MS = 3000;       // 3 seconds between polls
+const HITL_TIMEOUT_MS      = 10 * 60 * 1000; // 10 minute max wait for human
+
+let config = null;
+try {
+  config = JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf-8'));
+  console.log('[AMP Governance] Config loaded. Backend:', config.AMP_BACKEND_URL);
+} catch (err) {
+  console.error('[AMP Governance] Failed to load config:', err.message);
+}
+
+// Module-level instance cache so we only init once per process lifetime
+let _instanceId = null;
+
+function readSession() {
+  try {
+    return JSON.parse(fs.readFileSync(SESSION_FILE, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeSession(instanceId) {
+  try {
+    fs.writeFileSync(SESSION_FILE, JSON.stringify({ instanceId }), 'utf-8');
+  } catch (err) {
+    console.error('[AMP Governance] writeSession failed:', err.message);
+  }
+}
+
+// ── INSTANCE MANAGEMENT ──────────────────────────────────────────────────────
+
+/**
+ * Ensure an AMP instance exists for this session.
+ * Priority: in-memory cache → session file → create new via /api/agent/init.
+ */
+async function ensureInstance() {
+  if (!config) return null;
+
+  if (_instanceId) return _instanceId;
+
+  const session = readSession();
+  if (session?.instanceId) {
+    _instanceId = session.instanceId;
+    return _instanceId;
+  }
+
+  try {
+    const res = await fetch(`${config.AMP_BACKEND_URL}/api/agent/init`, {
+      method: 'POST',
+      headers: { 'X-API-Key': config.AMP_API_KEY, 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        agent_name: config.AGENT_NAME,
+        org_id:     config.AMP_ORG_ID,
+        username:   config.AMP_USERNAME,
+        prompt:     'OpenClaw governance session',
+        auto_start: true,
+        config:     { agent_mode: 'polling' },
+        metadata:   { source: 'openclaw-amp-plugin', owner: config.AMP_USERNAME },
+      }),
+    });
+    if (!res.ok) {
+      console.error(`[AMP Governance] /api/agent/init returned ${res.status}`);
+      return null;
+    }
+    const data = await res.json();
+    const id = data.instance_id;
+    if (id) {
+      _instanceId = id;
+      writeSession(id);
+      console.log(`[AMP Governance] AMP instance created: ${id}`);
+    }
+    return _instanceId || null;
+  } catch (err) {
+    console.error('[AMP Governance] ensureInstance failed:', err.message);
+    return null;
+  }
+}
+
+// ── AMP LOGGING ──────────────────────────────────────────────────────────────
+
+async function ampLog(instanceId, message, level = 'INFO') {
+  if (!config) return;
+  try {
+    await fetch(`${config.AMP_BACKEND_URL}/api/log`, {
+      method: 'POST',
+      headers: { 'X-API-Key': config.AMP_API_KEY, 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        instance_id: instanceId,
+        service:     config.AGENT_NAME,
+        level,
+        message,
+        timestamp:   new Date().toISOString(),
+        org_id:      config.AMP_ORG_ID,
+        username:    config.AMP_USERNAME,
+      }),
+    });
+  } catch (err) {
+    console.error('[AMP Governance] ampLog failed:', err.message);
+  }
+}
+
+// ── HITL POLICY ENGINE ───────────────────────────────────────────────────────
+
+/**
+ * Call /api/hitl/request with the tool call details.
+ * The AMP backend eval engine decides allow vs HITL.
+ */
+async function requestHitlEval(instanceId, tool, params) {
+  const res = await fetch(`${config.AMP_BACKEND_URL}/api/hitl/request`, {
+    method: 'POST',
+    headers: { 'X-API-Key': config.AMP_API_KEY, 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      caller_id:  instanceId,
+      instance_id: instanceId,
+      org_id:     config.AMP_ORG_ID,
+      agent_name: config.AGENT_NAME,
+      tool,
+      action:     params?.action || '*',
+      context:    params || {},
+      hitl: {
+        enable: true,
+        when:   'policy',
+        who:    config.AMP_USERNAME,
+        what:   'approval',
+        where:  'amp',
+      },
+    }),
+  });
+  if (!res.ok) throw new Error(`/api/hitl/request returned HTTP ${res.status}`);
+  return res.json();
+}
+
+/**
+ * Poll /api/hitl/get-decision until we get a 'complete' status or time out.
+ */
+async function pollHitlDecision(callerId) {
+  const deadline = Date.now() + HITL_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    await new Promise(r => setTimeout(r, HITL_POLL_INTERVAL_MS));
+    const res = await fetch(
+      `${config.AMP_BACKEND_URL}/api/hitl/get-decision?caller_id=${encodeURIComponent(callerId)}`,
+      { headers: { 'X-API-Key': config.AMP_API_KEY } }
+    );
+    if (!res.ok) {
+      console.warn(`[AMP Governance] get-decision returned ${res.status}, retrying...`);
+      continue;
+    }
+    const data = await res.json();
+    if (data.status === 'complete') return data;
+    console.log(`[AMP Governance] Waiting for human decision... (${data.status})`);
+  }
+  throw new Error(`HITL decision timed out after ${HITL_TIMEOUT_MS / 60000} minutes`);
+}
+
+/**
+ * Full governance check for a single tool call.
+ * Returns normally if the call is allowed (or approved by a human).
+ * Throws an Error with a clear reason if the call is blocked or rejected.
+ * Fails open (returns without throwing) if AMP backend is unreachable.
+ */
+/**
+ * Returns {} to allow, or { block: true, blockReason } to block.
+ * Never throws — errors fail open so infra issues don't break the agent.
+ */
+async function checkToolPolicy(instanceId, tool, params) {
+  const paramSummary = formatInput(tool, params);
+  await ampLog(instanceId, `Policy check: ${tool} | ${paramSummary}`);
+
+  let hitlResponse;
+  try {
+    hitlResponse = await requestHitlEval(instanceId, tool, params);
+  } 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 status = hitlResponse.status;
+  const reason = hitlResponse.reason || hitlResponse.information || '';
+  await ampLog(instanceId, `Policy decision: ${tool} | status=${status}${reason ? ` | ${reason}` : ''}`);
+
+  // ── No policy configured — block ─────────────────────────────────────────
+  if (status === 'no_policy') {
+    const msg = `Tool call "${tool}" blocked — no active governance policy for agent "${config.AGENT_NAME}". Contact your administrator.`;
+    await ampLog(instanceId, msg, 'WARN');
+    return { block: true, blockReason: msg };
+  }
+
+  // ── Eval engine approved — allow ─────────────────────────────────────────
+  if (status === 'no-hitl') {
+    console.log(`[AMP Governance] Policy approved: ${tool} (${reason || 'ok'})`);
+    return {};
+  }
+
+  // ── HITL required — wait for human decision ──────────────────────────────
+  if (status === 'pending' || status === 'waiting-for-response' || hitlResponse.workitem_id) {
+    console.log(`[AMP Governance] HITL required for "${tool}" — waiting for human decision...`);
+    await ampLog(instanceId, `HITL requested for tool: ${tool} — awaiting human approval in AMP`, 'WARN');
+
+    let decision;
+    try {
+      decision = await pollHitlDecision(instanceId);
+    } catch (err) {
+      const msg = `Tool call "${tool}" timed out waiting for human approval — blocked.`;
+      await ampLog(instanceId, msg, 'ERROR');
+      return { block: true, blockReason: msg };
+    }
+
+    const resolution = String(decision.resolution || '').toLowerCase().trim();
+    console.log(`[AMP Governance] HITL decision for "${tool}": ${resolution}`);
+
+    if (resolution === 'approve' || resolution === 'approved') {
+      await ampLog(instanceId, `HITL approved: ${tool} | workitem: ${decision.workitem_id}`);
+      return {};
+    }
+
+    if (resolution === 'modify' || resolution === 'modified') {
+      await ampLog(instanceId, `HITL approved with modification: ${tool} | workitem: ${decision.workitem_id}`);
+      return {};
+    }
+
+    // Rejected
+    const info = decision.information ? ` Reviewer note: ${decision.information}` : '';
+    const msg = `Tool call "${tool}" was rejected by a human reviewer.${info}`;
+    await ampLog(instanceId, `HITL rejected: ${tool} | workitem: ${decision.workitem_id}`, 'WARN');
+    return { block: true, blockReason: msg };
+  }
+
+  // Unknown response — fail open
+  console.warn('[AMP Governance] Unexpected HITL response:', JSON.stringify(hitlResponse));
+  await ampLog(instanceId, `Unexpected HITL response for ${tool}: ${JSON.stringify(hitlResponse)}`, 'WARN');
+  return {};
+}
+
+// ── TEXT FORMATTING HELPERS ──────────────────────────────────────────────────
+
+function extractText(obj) {
+  if (obj === undefined || obj === null) return '(empty)';
+  if (typeof obj === 'string') {
+    try { return extractText(JSON.parse(obj)); } catch { return obj; }
+  }
+  if (Array.isArray(obj)) {
+    return obj.map(extractText).filter(Boolean).join('\n');
+  }
+  if (typeof obj === 'object') {
+    if (obj.content && Array.isArray(obj.content)) {
+      return obj.content
+        .filter(c => c.text !== undefined)
+        .map(c => extractText(c.text))
+        .join('\n');
+    }
+    if (typeof obj.text === 'string') return extractText(obj.text);
+    return Object.entries(obj)
+      .filter(([k]) => k !== 'type')
+      .map(([k, v]) => `${k}: ${extractText(v)}`)
+      .join(' | ');
+  }
+  return String(obj);
+}
+
+function formatInput(tool, params) {
+  if (!params) return '';
+  try {
+    switch (tool) {
+      case 'web_search':
+        return `query: "${params.query}"${params.count ? ` (top ${params.count})` : ''}`;
+      case 'read':
+        return `path: ${params.path || params.file_path || JSON.stringify(params)}`;
+      case 'write':
+      case 'edit':
+        return `path: ${params.path || params.file_path || '?'}`;
+      case 'bash':
+      case 'shell':
+        return `cmd: ${String(params.command || params.cmd || '').substring(0, 120)}`;
+      default:
+        return extractText(params).substring(0, 200);
+    }
+  } catch {
+    return String(params).substring(0, 200);
+  }
+}
+
+function stripWrapper(s) {
+  if (typeof s !== 'string') return s;
+  return s
+    .replace(/<<<EXTERNAL_UNTRUSTED_CONTENT[^>]*>>>/g, '')
+    .replace(/<<<END_EXTERNAL_UNTRUSTED_CONTENT[^>]*>>>/g, '')
+    .replace(/Source:\s*Web Search\s*---/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function getRawText(result) {
+  try {
+    const obj = typeof result === 'string' ? JSON.parse(result) : result;
+    if (obj?.content && Array.isArray(obj.content)) {
+      const item = obj.content.find(c => c.text !== undefined);
+      if (item) return String(item.text);
+    }
+    if (typeof obj?.text === 'string') return obj.text;
+    return typeof result === 'string' ? result : JSON.stringify(result);
+  } catch {
+    return typeof result === 'string' ? result : '';
+  }
+}
+
+function formatOutput(tool, result) {
+  if (result === undefined || result === null) return '(empty)';
+  try {
+    switch (tool) {
+      case 'web_search': {
+        const raw = getRawText(result);
+        try {
+          const tavily = JSON.parse(raw);
+          const results = tavily?.externalContent?.results || tavily?.results || [];
+          if (results.length > 0) {
+            const lines = results.slice(0, 3).map((r, i) => {
+              const title   = stripWrapper(r.title || '');
+              const url     = r.url || '';
+              const snippet = stripWrapper(r.content || r.snippet || '').substring(0, 200);
+              return `[${i + 1}] ${title} › ${url} › ${snippet}`;
+            });
+            return `${results.length} result(s): ${lines.join(' ◆ ')}`;
+          }
+        } catch (e) {
+          console.error('[AMP Governance] web_search parse failed:', e.message);
+        }
+        return stripWrapper(raw).substring(0, 400);
+      }
+      case 'read': {
+        const text = extractText(result);
+        return text.substring(0, 300);
+      }
+      default:
+        return extractText(result).substring(0, 400);
+    }
+  } catch {
+    return String(result).substring(0, 300);
+  }
+}
+
+// ── PLUGIN REGISTRATION ──────────────────────────────────────────────────────
 
 export default {
   id: 'amp-governance',
   name: 'AMP Governance',
   description: 'AMP transparency, accountability, and HITL integration for OpenClaw',
   register(api) {
-    api.logger.info('AMP Governance registered. Phase 2 — before_tool_call discovery.');
+    api.logger.info('AMP Governance registered. Phase 4 - eval policy enforcement active.');
+
+    // ── BEFORE TOOL CALL: governance check + logging ─────────────────────────
+    api.on('before_tool_call', async (event) => {
+      const tool = event.toolName || event.name || 'unknown-tool';
+      if (SKIP_TOOLS.has(tool)) return {};
+
+      const instanceId = await ensureInstance();
+      if (!instanceId) {
+        console.warn('[AMP Governance] No instance available — skipping governance check.');
+        return {};
+      }
+
+      // Log the incoming tool call
+      const message = `Tool call: ${tool} | Input: ${formatInput(tool, event.params)}`;
+      console.log(`[AMP Governance] before_tool_call: ${tool} | instance: ${instanceId}`);
+      await ampLog(instanceId, message);
+
+      // Governance check — returns {} to allow or { block, blockReason } to block
+      return await checkToolPolicy(instanceId, tool, event.params);
+    });
+
+    // ── AFTER TOOL CALL: result logging ──────────────────────────────────────
+    api.on('after_tool_call', async (event) => {
+      const tool = event.toolName || event.name || 'unknown-tool';
+      if (SKIP_TOOLS.has(tool)) return;
+
+      const instanceId = _instanceId || readSession()?.instanceId;
+      if (!instanceId) return;
+
+      const result   = event.result ?? event.output ?? event.toolOutput;
+      const status   = event.success === false ? 'FAILED' : 'OK';
+      const duration = event.durationMs != null ? ` (${event.durationMs}ms)` : '';
+      const output   = formatOutput(tool, result);
+      const message  = `Tool result: ${tool} | Status: ${status}${duration} | ${output}`;
+
+      console.log(`[AMP Governance] after_tool_call: ${tool} | status: ${status}`);
+      await ampLog(instanceId, message, event.success === false ? 'ERROR' : 'INFO');
+    });
 
-    api.on('before_tool_call', (event) => {
-      console.log('[AMP Governance] before_tool_call fired:');
-      console.log(JSON.stringify(event, null, 2));
-      return {}; // do not block
+    // ── OUTBOUND MESSAGE LOGGING ──────────────────────────────────────────────
+    api.on('message_sending', async (event) => {
+      const instanceId = _instanceId || readSession()?.instanceId;
+      const msgText    = event.content || event.text || event.message || JSON.stringify(event);
+      const preview    = msgText.substring(0, 100);
+      console.log(`[AMP Governance] message_sending fired: ${preview}`);
+      if (instanceId) {
+        await ampLog(instanceId, `Agent reply: ${preview}`);
+      }
     });
   },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inquiryon/openclaw-amp-governance",
-  "version": "1.0.1",
+  "version": "1.0.4",
   "description": "AMP governance plugin for OpenClaw",
   "type": "module",
   "files": [