@aporthq/aport-agent-guardrails 1.0.21 → 1.0.23

package/README.md

@@ -97,7 +97,7 @@ The security concern is that agent tools and skills can execute sensitive action
 
 | Framework | Doc | Integration | Install |
 |-----------|-----|--------------|--------|
-| **OpenClaw** | [docs/frameworks/openclaw.md](docs/frameworks/openclaw.md) | Native `GuardrailProvider` or plugin | `npm i @aporthq/aport-agent-guardrails-core && npx @aporthq/aport-agent-guardrails openclaw` |
+| **OpenClaw** | [docs/frameworks/openclaw.md](docs/frameworks/openclaw.md) | **Plugin:** `before_tool_call` via `openclaw-aport` | `npx @aporthq/aport-agent-guardrails openclaw` |
 | **Cursor** | [docs/frameworks/cursor.md](docs/frameworks/cursor.md) | `beforeShellExecution` / `preToolUse` hooks → writes `~/.cursor/hooks.json`. **Runtime enforcement is the bash hook;** the Node package `@aporthq/aport-agent-guardrails-cursor` is a helper only (Evaluator, `getHookPath()`). | `npx @aporthq/aport-agent-guardrails cursor` |
 | **Claude Code** | [docs/frameworks/claude-code.md](docs/frameworks/claude-code.md) | PreToolUse hook → writes `~/.claude/settings.json` (Claude Code format; not Cursor). | `npx @aporthq/aport-agent-guardrails claude-code` |
 | **LangChain / LangGraph** | [docs/frameworks/langchain.md](docs/frameworks/langchain.md) | **Python:** `APortCallback` (`on_tool_start`) | `npx @aporthq/aport-agent-guardrails langchain` then `pip install aport-agent-guardrails-langchain` + `aport-langchain setup` |
@@ -126,13 +126,18 @@ npx @aporthq/aport-agent-guardrails
 # or: npx @aporthq/aport-agent-guardrails openclaw | cursor | claude-code | langchain | crewai | deerflow | n8n
 ```
 
-**Python (LangChain, CrewAI, or DeerFlow):** Run the wizard via the Node command above, then install the Python package and follow the printed next steps. Or use the Python CLI to see the exact commands:
+**Python (LangChain, CrewAI, or DeerFlow):** Use the Python CLI directly via `uvx` or an installed package:
+```bash
+uvx --from aport-agent-guardrails aport setup --framework=langchain
+# or --framework=crewai / deerflow
+```
+Or install the package first:
 ```bash
 pip install aport-agent-guardrails
 aport setup --framework=langchain
 # or --framework=crewai / deerflow
 ```
-Then run the printed `npx` command to create passport and config, and the printed Python integration step for your framework.
+Then install the framework-specific Python package and follow the printed integration step for your framework.
 
 This runs the **passport wizard** and writes config for your framework. Follow the **next steps** printed at the end (e.g. restart Cursor; or for CrewAI: by default install `aport-agent-guardrails-crewai` for released CrewAI, or opt into native-provider mode if your CrewAI build supports it).
 

package/bin/openclaw

@@ -1,7 +1,8 @@
 #!/bin/bash
 # OpenClaw + APort: interactive setup
-# Run from repo root. One run secures OpenClaw: creates passport, installs the
-# APort plugin (deterministic enforcement), writes config and guardrail wrappers.
+# Works from a repo checkout or from the published npm package via npx.
+# One run secures OpenClaw: creates a passport or wires a hosted agent_id,
+# installs the APort plugin, writes config, and installs guardrail wrappers.
 # After setup, start OpenClaw with the generated config (e.g. --config ~/.openclaw/config.yaml).
 #
 # Usage: ./bin/openclaw [agent_id]
@@ -29,6 +30,48 @@ REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 APORT_PLUGIN_PATH="$REPO_ROOT/extensions/openclaw-aport"
 DEFAULT_CONFIG="${OPENCLAW_HOME:-$HOME/.openclaw}"
 
+read_local_plugin_version() {
+    if ! command -v node >/dev/null 2>&1; then
+        return 0
+    fi
+    local package_json="$APORT_PLUGIN_PATH/package.json"
+    if [ ! -f "$package_json" ]; then
+        return 0
+    fi
+    node -e '
+const fs = require("node:fs");
+try {
+  const pkg = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
+  if (pkg && typeof pkg.version === "string") process.stdout.write(pkg.version);
+} catch {}
+' "$package_json"
+}
+
+read_installed_plugin_version() {
+    if ! command -v openclaw >/dev/null 2>&1 || ! command -v node >/dev/null 2>&1; then
+        return 0
+    fi
+    openclaw plugins list --json 2>/dev/null | node -e '
+let raw = "";
+process.stdin.on("data", (chunk) => {
+  raw += chunk;
+});
+process.stdin.on("end", () => {
+  const jsonStart = raw.indexOf("{");
+  if (jsonStart < 0) return;
+  try {
+    const data = JSON.parse(raw.slice(jsonStart));
+    const plugin = Array.isArray(data.plugins)
+      ? data.plugins.find((entry) => entry && entry.id === "openclaw-aport")
+      : null;
+    if (plugin && typeof plugin.version === "string") {
+      process.stdout.write(plugin.version);
+    }
+  } catch {}
+});
+'
+}
+
 # Parse command line arguments
 HOSTED_AGENT_ID=""
 if [ -n "$1" ]; then
@@ -209,15 +252,29 @@ if true; then
             echo "  Skipping plugin installation."
         fi
     else
+        LOCAL_PLUGIN_VERSION="$(read_local_plugin_version)"
+        INSTALLED_PLUGIN_VERSION="$(read_installed_plugin_version)"
         echo ""
-        echo "  Installing plugin from: $APORT_PLUGIN_PATH"
-        echo "  (Using -l to link local directory; OpenClaw accepts only registry or --link for install.)"
-        if openclaw plugins install -l "$APORT_PLUGIN_PATH" 2>&1; then
-            echo "  ✅ Plugin installed successfully"
+        if [ -n "$LOCAL_PLUGIN_VERSION" ] && [ "$LOCAL_PLUGIN_VERSION" = "$INSTALLED_PLUGIN_VERSION" ]; then
+            echo "  ✅ Plugin version $LOCAL_PLUGIN_VERSION already installed; skipping reinstall."
             PLUGIN_INSTALLED=true
         else
-            echo "  ⚠️  Plugin installation failed. You can install manually later:"
-            echo "     openclaw plugins install -l $APORT_PLUGIN_PATH"
+            if [ -n "$INSTALLED_PLUGIN_VERSION" ]; then
+                echo "  Existing openclaw-aport version: $INSTALLED_PLUGIN_VERSION"
+            fi
+            echo "  Installing plugin from: $APORT_PLUGIN_PATH"
+            echo "  (Using -l to link local directory; OpenClaw accepts only registry or --link for install.)"
+            if openclaw plugins install -l "$APORT_PLUGIN_PATH" 2>&1; then
+                echo "  ✅ Plugin installed successfully"
+                PLUGIN_INSTALLED=true
+            else
+                echo "  ❌ Plugin installation failed."
+                echo "     OpenClaw did not accept the plugin bundle, so setup is stopping here"
+                echo "     instead of writing plugin config that points at a broken install."
+                echo "     Retry after fixing the bundle or install it manually:"
+                echo "     openclaw plugins install -l $APORT_PLUGIN_PATH"
+                exit 1
+            fi
         fi
         echo ""
 
@@ -322,7 +379,7 @@ YAML
         # Passport file location (in aport/ subdir)
         passportFile: $PASSPORT_FILE
 
-        # For local mode: path to guardrail script
+        # Legacy compatibility field; current plugin versions use the built-in JS local evaluator
         guardrailScript: $CONFIG_DIR/.skills/aport-guardrail-bash.sh
 YAML
         fi
@@ -433,26 +490,21 @@ YAML
                 '{ mode: $mode, passportFile: $pf, guardrailScript: $gs, failClosed: true, allowUnmappedTools: ($allow_unmapped == "true") } + (if $mode == "api" then { apiUrl: $api_url } else {} end)')
         fi
 
-        if jq --argjson cfg "$CONFIG_JSON" --arg plugin_path "$APORT_PLUGIN_PATH" '
+        if jq --argjson cfg "$CONFIG_JSON" '
             .plugins = (.plugins // {}) |
             .plugins.entries = (.plugins.entries // {}) |
             .plugins.entries["openclaw-aport"] = ((.plugins.entries["openclaw-aport"] // {}) | .enabled = true | .config = $cfg) |
-            .plugins.load = (.plugins.load // {}) |
-            .plugins.load.paths = (
-                ((.plugins.load.paths // []) | map(select((type == "string" and contains("/openclaw-aport")) | not))) + [$plugin_path]
-            ) |
             .plugins.installs = (.plugins.installs // {}) |
-            .plugins.installs["openclaw-aport"] = ((.plugins.installs["openclaw-aport"] // {})
-                | .source = "path"
-                | .sourcePath = $plugin_path
-                | .installPath = $plugin_path)
+            del(.plugins.installs["openclaw-aport"]) |
+            .plugins.load = (.plugins.load // {}) |
+            .plugins.load.paths = ((.plugins.load.paths // []) | map(select((type == "string" and contains("/openclaw-aport")) | not)))
         ' "$OPENCLAW_JSON" > "$OPENCLAW_JSON.tmp" 2>/dev/null && { backup_file "$OPENCLAW_JSON"; mv "$OPENCLAW_JSON.tmp" "$OPENCLAW_JSON"; }; then
             if [ "$USE_HOSTED_PASSPORT" = true ]; then
                 echo "  ✅ Merged plugin config into $OPENCLAW_JSON (mode=$PLUGIN_MODE, hosted passport, allowUnmappedTools=$ALLOW_UNMAPPED)"
             else
                 echo "  ✅ Merged plugin config into $OPENCLAW_JSON (mode=$PLUGIN_MODE, allowUnmappedTools=$ALLOW_UNMAPPED)"
             fi
-            echo "  ✅ Canonicalized plugin load path → $APORT_PLUGIN_PATH"
+            echo "  ✅ Removed stale source-linked OpenClaw plugin paths from $OPENCLAW_JSON"
         fi
     fi
 
@@ -590,19 +642,18 @@ echo "   OpenClaw (or your code) calls the guardrail with a tool name and contex
 echo "   The guardrail maps that to a policy pack in external/aport-policies:"
 echo
 cat << 'TABLE'
-   Tool name (examples)              → Policy pack
-   ------------------------------------------------
-   git.create_pr, git.merge, git.*   → code.repository.merge.v1
-   exec.run, system.command.*       → system.command.execute.v1
-   message.send, messaging.*        → messaging.message.send.v1
-   mcp.tool.*, mcp.*                 → mcp.tool.execute.v1
-   agent.session.*, session.*       → agent.session.create.v1
-   agent.tool.*, tool.register      → agent.tool.register.v1
-   payment.refund, finance.*        → finance.payment.refund.v1
-   payment.charge                    → finance.payment.charge.v1
-   database.write, data.export       → data.export.create.v1
+	   Tool name (examples)              → Policy pack
+	   ------------------------------------------------
+	   git.create_pr, git.merge, git.*   → code.repository.merge.v1
+	   exec.run, system.command.*        → system.command.execute.v1
+	   message + send/reply/broadcast    → messaging.message.send.v1
+	   message + sendAttachment/react    → messaging.message.send.v1
+	   serverName__toolName, mcp__*      → mcp.tool.execute.v1
+	   read, glob, grep                  → data.file.read.v1
+	   write, edit, multiedit            → data.file.write.v1
 TABLE
-echo "   Full list: docs/TOOL_POLICY_MAPPING.md"
+echo "   Plugin mapping source: extensions/openclaw-aport/tool-mapping.js"
+echo "   Unmapped tools are allowed by default; set allowUnmappedTools: false for strict mode."
 echo
 
 # 5. Enforcement summary

package/docs/PROVIDER.md

@@ -8,7 +8,7 @@ APort ships a generic `OAPGuardrailProvider` for both Python and TypeScript. It
 Framework defines interface          APort implements it
 ────────────────────────             ───────────────────
 DeerFlow: GuardrailProvider    ←──   Python OAPGuardrailProvider
-OpenClaw: GuardrailProvider    ←──   TypeScript OAPGuardrailProvider
+TypeScript frameworks with a GuardrailProvider seam ←──   TypeScript OAPGuardrailProvider
 Your framework: same shape     ←──   Same class, same language
 ```
 
@@ -45,23 +45,23 @@ guardrails:
 ```typescript
 import { OAPGuardrailProvider } from "@aporthq/aport-agent-guardrails-core";
 
-const provider = new OAPGuardrailProvider({ framework: "openclaw" });
+const provider = new OAPGuardrailProvider({ framework: "your-framework" });
 const decision = await provider.evaluate(request);  // async
 const decision = provider.evaluateSync(request);     // sync
 ```
 
-**Supported frameworks:** OpenClaw, any TypeScript framework with a `GuardrailProvider` interface.
+**Supported frameworks:** TypeScript frameworks that expose a `GuardrailProvider` interface. Current public OpenClaw uses the plugin path documented in `docs/frameworks/openclaw.md`; a native provider path would be additive when upstream support exists.
 
-**Config:** `~/.openclaw/aport/config.yaml` or `~/.aport/<framework>/config.yaml`
+**Config:** `~/.aport/<framework>/config.yaml` or the framework-specific path your host expects
 
-**OpenClaw config.yaml:**
+**Example TypeScript host config:**
 ```yaml
 guardrails:
   enabled: true
   provider:
     use: "@aporthq/aport-agent-guardrails-core"
     config:
-      framework: "openclaw"
+      framework: "your-framework"
 ```
 
 ## What the provider does