@vaultclaw/vaultclaw-mcp-approval-handoff 0.1.2

package/README.md

@@ -0,0 +1,119 @@
+# Vaultclaw MCP Approval Handoff Plugin
+
+OpenClaw plugin that auto-handles Vaultclaw MCP approval handoff during agent tool runs.
+
+When a tool returns `MCP_APPROVAL_REQUIRED`, the plugin:
+
+- extracts `error.details.approval.next_action.arguments.handle`
+- notifies the user to approve/deny in Vaultclaw UI
+- asynchronously invokes `vaultclaw_approval_wait`
+- posts a single terminal update for `ALLOW`, `DENY`, or timeout
+- on `ALLOW`, auto-triggers one follow-up `agent` run for the same `sessionKey` so
+  compound flows continue without a manual "approved" message
+
+No second manual CLI command is required.
+
+## Install
+
+### Option A: npm package
+
+```bash
+openclaw plugins install @vaultclaw/vaultclaw-mcp-approval-handoff
+```
+
+### Option B: one-shot installer script (local checkout)
+
+```bash
+./scripts/install.sh
+```
+
+Optional npm/package override:
+
+```bash
+./scripts/install.sh @vaultclaw/vaultclaw-mcp-approval-handoff
+```
+
+## Config
+
+Plugin id: `vaultclaw-mcp-approval-handoff`
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "vaultclaw-mcp-approval-handoff": {
+        "enabled": true,
+        "config": {
+          "enabled": true,
+          "pollIntervalMs": 1500,
+          "maxWaitMs": 600000,
+          "commandTimeoutMs": 720000,
+          "maxConcurrentWaits": 10
+        }
+      }
+    }
+  }
+}
+```
+
+Validation rules:
+
+- `pollIntervalMs`: `250..10000`
+- `maxWaitMs`: `1000..3600000`
+- `commandTimeoutMs > maxWaitMs`
+- `maxConcurrentWaits >= 1`
+
+## Behavior
+
+- Scope: MCP tool results in OpenClaw agent runs.
+- Non-blocking: wait worker runs async from `after_tool_call`.
+- Supported handles: `JOB` and `PLAN_RUN`.
+- Dedupe key: `(session_id, challenge_id, pending_id, run_id/job_id)`.
+- Session lifecycle: pending waits are canceled on `before_reset` and `session_end`.
+- Retries: transient transport failures retry with backoff (`1s, 2s, 4s, 8s, 16s`, max 5 attempts).
+- No-retry terminal categories: validation/auth/timeouts.
+
+## Operational Limits
+
+- Wait calls are executed through the local Gateway HTTP route: `POST /tools/invoke`.
+- Gateway auth must allow that route (`token`/`password` via config or env, or `none`/`trusted-proxy` mode).
+- Status updates are posted through system events + heartbeat wake and require a valid `sessionKey`.
+- At most `maxConcurrentWaits` approval workers run in parallel.
+
+## Observability
+
+Structured plugin logs include:
+
+- `approval_detected`
+- `wait_started`
+- `wait_completed`
+- `wait_failed`
+- `wait_canceled`
+- `wait_retry`
+- `terminal_outcome`
+- `resume_started`
+- `resume_completed`
+- `resume_failed`
+- `cleanup`
+
+Each log includes correlation keys when available:
+
+- `session_id`
+- `challenge_id`
+- `pending_id`
+- `run_id` / `job_id`
+
+## Example Transcript
+
+1. User: "Trash the newsletter in Gmail from yesterday."
+2. Tool result: approval challenge returned (`MCP_APPROVAL_REQUIRED`).
+3. Plugin post: "Approval required in Vaultclaw UI. Waiting up to 10 minutes... (challenge_id=..., pending_id=..., run_id=...)"
+4. User approves in Vaultclaw UI.
+5. Plugin post: "Approval allowed in Vaultclaw UI. Continuing automatically. (...ids...)"
+
+## Development
+
+```bash
+npm install
+npm test
+```

package/index.ts

@@ -0,0 +1,127 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { ApprovalHandoffManager } from "./src/approval-manager.js";
+import { normalizePluginConfig } from "./src/config.js";
+import { createGatewayAgentResumeInvoker } from "./src/resume-invoker.js";
+import { createGatewayToolsInvokeWaitInvoker } from "./src/wait-invoker.js";
+
+const plugin = {
+  id: "vaultclaw-mcp-approval-handoff",
+  name: "Vaultclaw MCP Approval Handoff",
+  description: "Automatically waits MCP approval challenges and posts terminal outcomes.",
+  configSchema: {
+    parse(value: unknown) {
+      return normalizePluginConfig(value);
+    },
+    uiHints: {
+      enabled: {
+        label: "Enable Auto Approval Wait",
+      },
+      pollIntervalMs: {
+        label: "Poll Interval (ms)",
+      },
+      maxWaitMs: {
+        label: "Max Wait (ms)",
+      },
+      commandTimeoutMs: {
+        label: "Command Timeout (ms)",
+      },
+      maxConcurrentWaits: {
+        label: "Max Concurrent Waits",
+      },
+    },
+  },
+  register(api: OpenClawPluginApi) {
+    const resolveSessionKey = (ctx: any): string | undefined => {
+      const explicit = typeof ctx?.sessionKey === "string" ? ctx.sessionKey.trim() : "";
+      if (explicit) {
+        return explicit;
+      }
+      const sessionId = typeof ctx?.sessionId === "string" ? ctx.sessionId.trim() : "";
+      if (sessionId && sessionId.startsWith("agent:")) {
+        return sessionId;
+      }
+      const agentId = typeof ctx?.agentId === "string" ? ctx.agentId.trim() : "";
+      if (agentId) {
+        return `agent:${agentId}:main`;
+      }
+      return "agent:main:main";
+    };
+
+    const config = normalizePluginConfig(api.pluginConfig);
+    const waitInvoker = createGatewayToolsInvokeWaitInvoker(api.config);
+    const resumeInvoker = typeof api.runtime?.system?.runCommandWithTimeout === "function"
+      ? createGatewayAgentResumeInvoker({
+        runCommandWithTimeout: api.runtime.system.runCommandWithTimeout,
+      })
+      : undefined;
+
+    const manager = new ApprovalHandoffManager({
+      config,
+      waitInvoker,
+      resumeInvoker,
+      logger: api.logger,
+      notifier: {
+        post: ({ sessionKey, text, reason, contextKey }) => {
+          const scopedSessionKey = sessionKey?.trim();
+          if (!scopedSessionKey) {
+            api.logger.warn(
+              `[vaultclaw-approval-handoff] skipped notification with no sessionKey: ${text}`,
+            );
+            return;
+          }
+          try {
+            api.runtime.system.enqueueSystemEvent(text, {
+              sessionKey: scopedSessionKey,
+              contextKey,
+            });
+            const requestHeartbeatNow = api.runtime?.system?.requestHeartbeatNow;
+            if (typeof requestHeartbeatNow === "function") {
+              requestHeartbeatNow({
+                reason: `vaultclaw-approval-handoff:${reason}`,
+                sessionKey: scopedSessionKey,
+              });
+            }
+          } catch (error) {
+            api.logger.warn(
+              `[vaultclaw-approval-handoff] failed to enqueue system event: ${String(error)}`,
+            );
+          }
+        },
+      },
+    });
+
+    api.on("after_tool_call", (event: any, ctx: any) => {
+      const sessionKey = resolveSessionKey(ctx);
+      manager.onAfterToolCall(
+        {
+          toolName: event.toolName,
+          result: event.result,
+          runId: event.runId,
+        },
+        {
+          sessionId: ctx.sessionId ?? sessionKey,
+          sessionKey,
+          runId: ctx.runId,
+        },
+      );
+    });
+
+    api.on("before_reset", (event: any, ctx: any) => {
+      const sessionKey = resolveSessionKey(ctx);
+      manager.onBeforeReset(event, {
+        sessionId: ctx.sessionId ?? sessionKey,
+        sessionKey,
+      });
+    });
+
+    api.on("session_end", (event: any, ctx: any) => {
+      const sessionKey = resolveSessionKey(ctx);
+      manager.onSessionEnd(event, {
+        sessionId: ctx.sessionId ?? sessionKey,
+        sessionKey,
+      });
+    });
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,57 @@
+{
+  "id": "vaultclaw-mcp-approval-handoff",
+  "name": "Vaultclaw MCP Approval Handoff",
+  "description": "Auto-resume Vaultclaw MCP approval-required tool flows.",
+  "version": "0.1.0",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "enabled": {
+        "type": "boolean",
+        "default": true
+      },
+      "pollIntervalMs": {
+        "type": "integer",
+        "default": 1500,
+        "minimum": 250,
+        "maximum": 10000
+      },
+      "maxWaitMs": {
+        "type": "integer",
+        "default": 600000,
+        "minimum": 1000,
+        "maximum": 3600000
+      },
+      "commandTimeoutMs": {
+        "type": "integer",
+        "default": 720000,
+        "minimum": 1001,
+        "maximum": 7200000
+      },
+      "maxConcurrentWaits": {
+        "type": "integer",
+        "default": 10,
+        "minimum": 1,
+        "maximum": 100
+      }
+    }
+  },
+  "uiHints": {
+    "enabled": {
+      "label": "Enable Auto Approval Wait"
+    },
+    "pollIntervalMs": {
+      "label": "Poll Interval (ms)"
+    },
+    "maxWaitMs": {
+      "label": "Max Wait (ms)"
+    },
+    "commandTimeoutMs": {
+      "label": "Command Timeout (ms)"
+    },
+    "maxConcurrentWaits": {
+      "label": "Max Concurrent Waits"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@vaultclaw/vaultclaw-mcp-approval-handoff",
+  "version": "0.1.2",
+  "description": "OpenClaw plugin that auto-waits Vaultclaw MCP approvals",
+  "type": "module",
+  "files": [
+    "index.ts",
+    "openclaw.plugin.json",
+    "src",
+    "scripts/install.sh",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "openclaw": "^2026.3.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

package/scripts/install.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env sh
+set -eu
+
+PLUGIN_ID="vaultclaw-mcp-approval-handoff"
+SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
+ROOT_DIR="$(CDPATH= cd -- "$SCRIPT_DIR/.." && pwd)"
+EXT_DIR="${HOME}/.openclaw/extensions/${PLUGIN_ID}"
+
+SPEC="${1:-$ROOT_DIR}"
+
+echo "Installing plugin from: $SPEC"
+if openclaw plugins info "$PLUGIN_ID" >/dev/null 2>&1; then
+  echo "Existing plugin detected, uninstalling old copy..."
+  openclaw plugins uninstall "$PLUGIN_ID" --force || true
+fi
+if [ -d "$EXT_DIR" ]; then
+  echo "Removing stale extension directory: $EXT_DIR"
+  rm -rf "$EXT_DIR"
+fi
+
+openclaw plugins install "$SPEC"
+openclaw plugins enable "$PLUGIN_ID" || true
+
+openclaw config set "plugins.entries.$PLUGIN_ID.config.enabled" true
+openclaw config set "plugins.entries.$PLUGIN_ID.config.pollIntervalMs" 1500
+openclaw config set "plugins.entries.$PLUGIN_ID.config.maxWaitMs" 600000
+openclaw config set "plugins.entries.$PLUGIN_ID.config.commandTimeoutMs" 720000
+openclaw config set "plugins.entries.$PLUGIN_ID.config.maxConcurrentWaits" 10
+
+echo "Plugin installed and configured: $PLUGIN_ID"
+echo "Restart the gateway to apply config if it is already running: openclaw gateway restart"