aquaman-plugin 0.9.2 → 0.11.0

package/README.md

@@ -1,19 +1,20 @@
-# aquaman-plugin
+# Aquaman — API Key Protection for OpenClaw
 
-OpenClaw Gateway plugin for [aquaman](https://github.com/tech4242/aquaman) credential isolation.
-
-## How It Works
+Your API keys and tokens stay in your vault. The agent never sees them.
+Even a compromised agent can't steal credentials — they live in a
+separate process.
 
 ```
 Agent / OpenClaw Gateway              Aquaman Proxy
 ┌──────────────────────┐              ┌──────────────────────┐
 │                      │              │                      │
-│  ANTHROPIC_BASE_URL  │══ Unix ════>│  Keychain / 1Pass /  │
-│  = aquaman.local     │   Domain    │  Vault / Encrypted   │
-│                      │<═ Socket ═══│                      │
-│  fetch() interceptor │══ (UDS) ══=>│  + Auth injected:    │
-│  redirects channel   │              │    header / url-path │
-│  API traffic         │              │    basic / oauth     │
+│  ANTHROPIC_BASE_URL  │══ Unix ═════>│  Keychain / 1Pass /  │
+│  = aquaman.local     │   Domain     │  Vault / Encrypted   │
+│                      │<═ Socket ════│                      │
+│  fetch() interceptor │══ (UDS) ════>│  + Policy enforced   │
+│  redirects channel   │              │  + Auth injected:    │
+│  API traffic         │              │    header / url-path │
+│                      │              │    basic / oauth     │
 │                      │              │                      │
 │  No credentials.     │  ~/.aquaman/ │                      │
 │  No open ports.      │  proxy.sock  │                      │
@@ -30,25 +31,42 @@ Agent / OpenClaw Gateway              Aquaman Proxy
                                slack.com/api  ...
 ```
 
-This plugin makes the left side work. It routes all LLM and channel API traffic through the aquaman proxy via Unix domain socket so credentials never enter the Gateway process. No TCP port is opened — traffic flows through `~/.aquaman/proxy.sock`.
+## What It Does
+
+1. **Secrets stay in your vault** — Keychain, 1Password, HashiCorp Vault, KeePassXC, systemd-creds, Bitwarden, or encrypted file
+2. **Agent gets a proxy URL** — requests route through a local proxy that injects auth headers on the fly
+3. **Dangerous endpoints blocked** — request policies deny admin APIs, prevent deletions, block sends — before credentials are even injected
+4. **Tamper-evident audit log** — every credential use logged with SHA-256 hash chains
 
 ## Quick Start
 
 ```bash
-npm install -g aquaman-proxy              # install the proxy CLI
-aquaman setup                             # stores keys, installs plugin, configures OpenClaw
-openclaw                                  # proxy starts automatically
+openclaw plugins install aquaman-plugin   # 1. install plugin + proxy
+openclaw aquaman setup                    # 2. store your API keys
+openclaw                                  # 3. done — proxy starts automatically
 ```
 
-> `aquaman setup` auto-detects your credential backend. macOS defaults to Keychain,
-> Linux defaults to encrypted file. Override with `--backend`:
-> `aquaman setup --backend keepassxc`
-> Options: `keychain`, `encrypted-file`, `keepassxc`, `1password`, `vault`, `systemd-creds`, `bitwarden`
+> **Using npm?** `npm install -g aquaman-proxy && aquaman setup` does
+> the same thing. Use this if you prefer managing packages with npm.
+
+## Available Commands
+
+All commands work via OpenClaw CLI or your terminal:
+
+| OpenClaw CLI | Terminal | Description |
+|---|---|---|
+| `openclaw aquaman setup` | `aquaman setup` | Onboarding wizard — stores keys, configures backend |
+| `openclaw aquaman doctor` | `aquaman doctor` | Diagnostic checks with actionable fixes |
+| `openclaw aquaman credentials list` | `aquaman credentials list` | List stored credentials |
+| `openclaw aquaman credentials add` | `aquaman credentials add` | Add a credential (interactive) |
+| `openclaw aquaman policy-list` | `aquaman policy list` | Show request policy rules |
+| `openclaw aquaman audit-tail` | `aquaman audit tail` | Recent audit entries |
+| `openclaw aquaman services-list` | `aquaman services list` | List configured services |
+| `openclaw aquaman status` | `aquaman status` | Proxy status |
 
-Existing plaintext credentials are migrated automatically during setup.
-Run again anytime to migrate new credentials: `aquaman migrate openclaw --auto`
+Slash commands in chat: `/aquaman-status`, `/aquaman list`, `/aquaman doctor`
 
-Troubleshooting: `aquaman doctor`
+Troubleshooting: `openclaw aquaman doctor` or `aquaman doctor`
 
 ## Config Options
 
@@ -59,20 +77,20 @@ Troubleshooting: `aquaman doctor`
 | `backend` | `"keychain"` \| `"1password"` \| `"vault"` \| `"encrypted-file"` \| `"keepassxc"` \| `"systemd-creds"` \| `"bitwarden"` | `"keychain"` | Credential store |
 | `services` | `string[]` | `["anthropic", "openai"]` | Services to proxy |
 
-> Advanced settings (audit, vault) go in `~/.aquaman/config.yaml`.
+> Advanced settings (audit, vault, request policies) go in `~/.aquaman/config.yaml`. See [request policy docs](https://github.com/tech4242/aquaman#request-policies).
 
-## Security Audit Note
+## Security Audit
 
-Running `openclaw security audit --deep` will show two expected findings:
+`openclaw security audit --deep` reports two expected findings:
 
-- **`dangerous-exec`** on `proxy-manager.ts` — the plugin spawns the aquaman proxy as a separate process, which is the whole point of credential isolation.
-- **`tools_reachable_permissive_policy`** — advisory that plugin tools are reachable under the default tool policy. This is about your OpenClaw tool profile setting, not about aquaman. Set `"tools": { "profile": "coding" }` in `openclaw.json` if your agents handle untrusted input.
+- **`dangerous-exec`** on `proxy-manager.ts` — the plugin spawns the proxy as a separate process. This is how credential isolation works.
+- **`tools_reachable_permissive_policy`** — advisory about your tool policy, not an aquaman vulnerability. Set `"tools": { "profile": "coding" }` in `openclaw.json` if your agents handle untrusted input.
 
-`aquaman setup` adds the plugin to your `plugins.allow` trust list automatically.
+`aquaman setup` adds the plugin to `plugins.allow` automatically.
 
 ## Documentation
 
-See the [main README](https://github.com/tech4242/aquaman#readme) for architecture, Docker deployment, and manual testing.
+See the [main README](https://github.com/tech4242/aquaman#readme) for the full security model, architecture diagrams, request policy config, and manual testing guides.
 
 ## License
 

package/index.ts

@@ -16,10 +16,53 @@
  *   - Agent never sees the actual API keys
  */
 
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+// OpenClaw plugin SDK types — defined locally to avoid import resolution failures.
+// The root import "openclaw/plugin-sdk" broke for user-installed plugins in OpenClaw 2026.3.23
+// (GitHub issue #53403: jiti resolver can't walk from ~/.openclaw/extensions/ to OpenClaw's
+// package tree). Since we only use these as compile-time types, local definitions are zero-risk
+// and make the plugin resilient to SDK path changes. Revert to SDK import if OpenClaw stabilizes
+// module resolution for user-installed plugins.
+
+interface OpenClawPluginLogger {
+  info(msg: string): void;
+  warn(msg: string): void;
+  error(msg: string): void;
+}
+
+interface OpenClawPluginApi {
+  logger: OpenClawPluginLogger;
+  pluginConfig: unknown;
+  registerService(def: {
+    id: string;
+    start(ctx: { logger: OpenClawPluginLogger }): void | Promise<void>;
+    stop(ctx: { logger: OpenClawPluginLogger }): void | Promise<void>;
+  }): void;
+  registerCommand(def: {
+    name: string;
+    description: string;
+    acceptsArgs: boolean;
+    requireAuth: boolean;
+    handler(): Promise<{ text: string }>;
+  }): void;
+  registerCli?(
+    fn: (opts: { program: any }) => void,
+    opts: { commands: string[] },
+  ): void;
+  registerTool(
+    factory: () => {
+      name: string;
+      label: string;
+      description: string;
+      parameters: { type: "object"; properties: Record<string, unknown>; required: string[] };
+      execute(toolCallId: string, params: unknown): Promise<{
+        content: { type: "text"; text: string }[];
+        details: unknown;
+      }>;
+    },
+    opts: { names: string[] },
+  ): void;
+}
 
-// OpenClawPluginDefinition exists in the SDK internals but isn't re-exported from "openclaw/plugin-sdk".
-// Mirror the type here until OpenClaw exposes it from the barrel.
 type OpenClawPluginDefinition = {
   id?: string;
   name?: string;
@@ -31,7 +74,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import * as os from "node:os";
 import { HttpInterceptor, createHttpInterceptor } from "./src/http-interceptor.js";
-import { createProxyManager, type ProxyManager } from "./src/proxy-manager.js";
+import { createProxyManager, findAquamanProxyBinary, execAquamanProxyCli, execAquamanProxyInteractive, type ProxyManager } from "./src/proxy-manager.js";
 import { loadHostMap, isProxyRunning, getProxyVersion } from "./src/proxy-health.js";
 
 /**
@@ -102,10 +145,10 @@ const FALLBACK_HOST_MAP = new Map<string, string>([
 ]);
 
 /**
- * Check if aquaman CLI is installed (fs-based, no shell execution)
+ * Check if aquaman proxy binary is available (local node_modules or PATH)
  */
-function isAquamanInstalled(): boolean {
-  return findInPath("aquaman") !== null;
+function isAquamanProxyInstalled(): boolean {
+  return findAquamanProxyBinary() !== null;
 }
 
 /**
@@ -205,7 +248,34 @@ function configureEnvironment(log: OpenClawPluginApi["logger"], services: string
 }
 
 /**
- * Register the aquaman_status tool
+ * Build status object for both the tool and slash command
+ */
+function getStatus(services: string[]) {
+  const cliInstalled = isAquamanProxyInstalled();
+  return {
+    cliInstalled,
+    proxyRunning: proxyManager !== null,
+    socketPath: socketPath || getDefaultSocketPath(),
+    services,
+    httpInterceptorActive: httpInterceptor?.isActive() ?? false,
+    ...(cliInstalled ? {} : { fix: "Run: npm install -g aquaman-proxy && aquaman setup" }),
+    ...(!cliInstalled ? {} : proxyManager === null ? { fix: "Run: aquaman setup (or: openclaw aquaman setup)" } : {}),
+    environmentVariables: Object.fromEntries(
+      services.map((s) => {
+        const key =
+          s === "anthropic"
+            ? "ANTHROPIC_BASE_URL"
+            : s === "openai"
+              ? "OPENAI_BASE_URL"
+              : `${s.toUpperCase()}_BASE_URL`;
+        return [key, process.env[key] ?? null];
+      })
+    ),
+  };
+}
+
+/**
+ * Register the aquaman_status tool — always registered (works in degraded mode)
  */
 function registerStatusTool(api: OpenClawPluginApi, services: string[]): void {
   api.registerTool(
@@ -221,23 +291,7 @@ function registerStatusTool(api: OpenClawPluginApi, services: string[]): void {
           required: [] as string[],
         },
         async execute(_toolCallId: string, _params: unknown) {
-          const status = {
-            proxyRunning: proxyManager !== null,
-            socketPath: socketPath || getDefaultSocketPath(),
-            services,
-            httpInterceptorActive: httpInterceptor?.isActive() ?? false,
-            environmentVariables: Object.fromEntries(
-              services.map((s) => {
-                const key =
-                  s === "anthropic"
-                    ? "ANTHROPIC_BASE_URL"
-                    : s === "openai"
-                      ? "OPENAI_BASE_URL"
-                      : `${s.toUpperCase()}_BASE_URL`;
-                return [key, process.env[key] ?? null];
-              })
-            ),
-          };
+          const status = getStatus(services);
           return {
             content: [{ type: "text" as const, text: JSON.stringify(status, null, 2) }],
             details: status,
@@ -299,9 +353,9 @@ function ensureAuthProfiles(log: OpenClawPluginApi["logger"], services: string[]
  */
 const plugin: OpenClawPluginDefinition = {
   id: 'aquaman-plugin',
-  name: 'Aquaman Vault',
+  name: 'Aquaman — API Key Protection',
   version: PLUGIN_VERSION,
-  description: 'Credential isolation for OpenClaw — API keys never enter the agent process',
+  description: 'API key protection for OpenClaw — credentials stay in your vault, never in the agent\'s memory',
 
   register(api) {
     api.logger.info("Aquaman plugin loaded");
@@ -313,70 +367,76 @@ const plugin: OpenClawPluginDefinition = {
     // Auto-generate auth-profiles.json if missing
     ensureAuthProfiles(api.logger, configuredServices);
 
-    // Local proxy mode — requires aquaman CLI
-    if (!isAquamanInstalled()) {
+    // Check if aquaman proxy binary is available
+    const proxyAvailable = isAquamanProxyInstalled();
+
+    if (!proxyAvailable) {
       api.logger.warn(
-        "aquaman CLI not found. Install with: npm install -g aquaman-proxy"
+        "aquaman proxy not found. Install with: npm install -g aquaman-proxy"
       );
       api.logger.warn(
         "Then run: aquaman setup"
       );
-      configureEnvironment(api.logger, configuredServices);
-      return;
-    }
-
-    api.logger.info("aquaman CLI found, will start proxy on gateway start");
+      // DO NOT call configureEnvironment() — sentinel URLs without a proxy
+      // would break all API calls (connection refused to non-existent socket)
+    } else {
+      api.logger.info("aquaman proxy found, will start proxy on gateway start");
 
-    // Configure environment variables immediately (sentinel hostname)
-    configureEnvironment(api.logger, configuredServices);
-
-    // Register service for proxy lifecycle management
-    api.registerService({
-      id: 'aquaman-proxy',
-      async start(ctx) {
-        ctx.logger.info("Starting aquaman proxy...");
-
-        const started = await startProxy(ctx.logger);
-        if (started && socketPath) {
-          ctx.logger.info("Aquaman proxy started successfully");
-
-          // Check for version mismatch between plugin and proxy
-          const proxyVersion = await getProxyVersion(socketPath);
-          if (proxyVersion && proxyVersion !== PLUGIN_VERSION) {
-            ctx.logger.warn(
-              `Warning: plugin version ${PLUGIN_VERSION} \u2260 proxy version ${proxyVersion}. ` +
-              `Update both: npm install -g aquaman-proxy && openclaw plugins install aquaman-plugin`
-            );
-          }
+      // Configure environment variables immediately (sentinel hostname)
+      configureEnvironment(api.logger, configuredServices);
 
-          // Activate HTTP interceptor to redirect channel traffic through proxy
-          activateHttpInterceptor(ctx.logger);
-        } else {
-          ctx.logger.error("Failed to start aquaman proxy");
-          // Check if another instance is already running
-          const defaultSock = getDefaultSocketPath();
-          const alreadyRunning = await isProxyRunning(defaultSock);
-          if (alreadyRunning) {
-            socketPath = defaultSock;
-            ctx.logger.info(
-              "Another aquaman instance is already running — using it"
-            );
-            // Load host map from existing proxy
-            const map = await loadHostMap(defaultSock);
-            dynamicHostMap = map.size > 0 ? map : FALLBACK_HOST_MAP;
+      // Register service for proxy lifecycle management
+      api.registerService({
+        id: 'aquaman-proxy',
+        async start(ctx) {
+          ctx.logger.info("Starting aquaman proxy...");
+
+          const started = await startProxy(ctx.logger);
+          if (started && socketPath) {
+            ctx.logger.info("Aquaman proxy started successfully");
+
+            // Check for version mismatch between plugin and proxy
+            const proxyVersion = await getProxyVersion(socketPath);
+            if (proxyVersion && proxyVersion !== PLUGIN_VERSION) {
+              ctx.logger.warn(
+                `Warning: plugin version ${PLUGIN_VERSION} \u2260 proxy version ${proxyVersion}. ` +
+                `Update both: npm install -g aquaman-proxy && openclaw plugins install aquaman-plugin`
+              );
+            }
+
+            // Activate HTTP interceptor to redirect channel traffic through proxy
             activateHttpInterceptor(ctx.logger);
           } else {
-            ctx.logger.error(
-              "No running proxy found. Check: aquaman doctor"
-            );
+            ctx.logger.error("Failed to start aquaman proxy");
+            // Check if another instance is already running
+            const defaultSock = getDefaultSocketPath();
+            const alreadyRunning = await isProxyRunning(defaultSock);
+            if (alreadyRunning) {
+              socketPath = defaultSock;
+              ctx.logger.info(
+                "Another aquaman instance is already running — using it"
+              );
+              // Load host map from existing proxy
+              const map = await loadHostMap(defaultSock);
+              dynamicHostMap = map.size > 0 ? map : FALLBACK_HOST_MAP;
+              activateHttpInterceptor(ctx.logger);
+            } else {
+              ctx.logger.error(
+                "No running proxy found. Check: openclaw aquaman doctor"
+              );
+            }
           }
+        },
+        async stop(ctx) {
+          ctx.logger.info("Stopping aquaman proxy...");
+          stopProxy();
         }
-      },
-      async stop(ctx) {
-        ctx.logger.info("Stopping aquaman proxy...");
-        stopProxy();
-      }
-    });
+      });
+    }
+
+    // --- Commands, tools, and CLI are ALWAYS registered (even without proxy) ---
+    // This ensures ClawHub users who installed the plugin but haven't run setup
+    // still get actionable commands and status information.
 
     // Register /aquaman-status slash command for humans
     api.registerCommand({
@@ -385,12 +445,7 @@ const plugin: OpenClawPluginDefinition = {
       acceptsArgs: false,
       requireAuth: true,
       async handler() {
-        const status = {
-          proxyRunning: proxyManager !== null,
-          socketPath: socketPath || getDefaultSocketPath(),
-          services: configuredServices,
-          httpInterceptorActive: httpInterceptor?.isActive() ?? false,
-        };
+        const status = getStatus(configuredServices);
         return { text: JSON.stringify(status, null, 2) };
       }
     });
@@ -401,40 +456,128 @@ const plugin: OpenClawPluginDefinition = {
         ({ program }) => {
           const aquamanCmd = program
             .command("aquaman")
-            .description("Aquaman credential management");
+            .description("Aquaman — API key protection");
 
           aquamanCmd
             .command("status")
             .description("Show aquaman proxy status")
             .action(() => {
+              const status = getStatus(configuredServices);
               console.log("\nAquaman Status:");
-              console.log(`  Proxy running: ${proxyManager !== null}`);
-              console.log(`  Socket path: ${socketPath || getDefaultSocketPath()}`);
+              console.log(`  Proxy binary: ${status.cliInstalled ? "found" : "NOT FOUND"}`);
+              console.log(`  Proxy running: ${status.proxyRunning}`);
+              console.log(`  Socket path: ${status.socketPath}`);
               console.log(`  Services: ${configuredServices.join(", ")}`);
-              console.log("\nEnvironment Variables:");
-              for (const service of configuredServices) {
-                const envKey =
-                  service === "anthropic"
-                    ? "ANTHROPIC_BASE_URL"
-                    : service === "openai"
-                      ? "OPENAI_BASE_URL"
-                      : `${service.toUpperCase()}_BASE_URL`;
-                console.log(`  ${envKey}=${process.env[envKey] ?? "(not set)"}`);
+              if (status.fix) {
+                console.log(`\n  Action needed: ${status.fix}`);
+              }
+              if (status.proxyRunning) {
+                console.log("\nEnvironment Variables:");
+                for (const service of configuredServices) {
+                  const envKey =
+                    service === "anthropic"
+                      ? "ANTHROPIC_BASE_URL"
+                      : service === "openai"
+                        ? "OPENAI_BASE_URL"
+                        : `${service.toUpperCase()}_BASE_URL`;
+                  console.log(`  ${envKey}=${process.env[envKey] ?? "(not set)"}`);
+                }
               }
             });
 
           aquamanCmd
-            .command("add <service> [key]")
-            .description("Add a credential (opens secure prompt)")
-            .action((service: string, key: string = "api_key") => {
-              console.log(`\n  Run in your terminal:\n    aquaman credentials add ${service} ${key}\n`);
+            .command("setup")
+            .description("Run the setup wizard (stores keys, configures backend)")
+            .action(async () => {
+              try {
+                const exitCode = await execAquamanProxyInteractive(['setup']);
+                if (exitCode !== 0) process.exitCode = exitCode;
+              } catch {
+                console.log("\n  Run in your terminal:\n    aquaman setup\n");
+              }
             });
 
           aquamanCmd
+            .command("doctor")
+            .description("Diagnose issues with actionable fixes")
+            .action(async () => {
+              try {
+                const result = await execAquamanProxyCli(['doctor']);
+                process.stdout.write(result.stdout);
+                if (result.stderr) process.stderr.write(result.stderr);
+                if (result.exitCode !== 0) process.exitCode = result.exitCode;
+              } catch (err: any) {
+                console.error(`Failed to run aquaman doctor: ${err.message}`);
+                process.exitCode = 1;
+              }
+            });
+
+          const credsCmd = aquamanCmd
+            .command("credentials")
+            .description("Credential management");
+
+          credsCmd
             .command("list")
             .description("List stored credentials")
-            .action(() => {
-              console.log(`\n  Run in your terminal:\n    aquaman credentials list\n`);
+            .action(async () => {
+              try {
+                const result = await execAquamanProxyCli(['credentials', 'list']);
+                process.stdout.write(result.stdout);
+                if (result.stderr) process.stderr.write(result.stderr);
+              } catch (err: any) {
+                console.error(`Failed: ${err.message}`);
+              }
+            });
+
+          credsCmd
+            .command("add <service> [key]")
+            .description("Add a credential (secure prompt)")
+            .action(async (service: string, key: string = "api_key") => {
+              try {
+                const exitCode = await execAquamanProxyInteractive(['credentials', 'add', service, key]);
+                if (exitCode !== 0) process.exitCode = exitCode;
+              } catch {
+                console.log(`\n  Run in your terminal:\n    aquaman credentials add ${service} ${key}\n`);
+              }
+            });
+
+          aquamanCmd
+            .command("policy-list")
+            .description("List configured request policy rules")
+            .action(async () => {
+              try {
+                const result = await execAquamanProxyCli(['policy', 'list']);
+                process.stdout.write(result.stdout);
+                if (result.stderr) process.stderr.write(result.stderr);
+              } catch (err: any) {
+                console.error(`Failed: ${err.message}`);
+              }
+            });
+
+          aquamanCmd
+            .command("audit-tail")
+            .description("Show recent audit log entries")
+            .action(async () => {
+              try {
+                const result = await execAquamanProxyCli(['audit', 'tail']);
+                process.stdout.write(result.stdout);
+                if (result.stderr) process.stderr.write(result.stderr);
+              } catch (err: any) {
+                console.error(`Failed: ${err.message}`);
+              }
+            });
+
+          aquamanCmd
+            .command("services-list")
+            .description("List all configured services")
+            .action(async () => {
+              try {
+                const result = await execAquamanProxyCli(['services', 'list']);
+                process.stdout.write(result.stdout);
+                if (result.stderr) process.stderr.write(result.stderr);
+              } catch (err: any) {
+                console.error(`Failed: ${err.message}`);
+              }
             });
         },
         { commands: ["aquaman"] }

package/openclaw.plugin.json

@@ -1,7 +1,11 @@
 {
   "id": "aquaman-plugin",
-  "name": "Aquaman Vault",
-  "description": "Credential isolation - API keys never touch the agent process",
+  "name": "Aquaman — API Key Protection",
+  "version": "0.11.0",
+  "description": "Protect your API keys, tokens, and secrets — they stay in your vault (Keychain, 1Password, HashiCorp Vault, Bitwarden, and more), never in the agent's memory. Block dangerous API endpoints before credentials are injected. Works with 25+ services across 6 auth modes.",
+  "author": "tech4242",
+  "repository": "https://github.com/tech4242/aquaman",
+  "license": "MIT",
   "permissions": {
     "env:write": ["*_BASE_URL", "GITHUB_API_URL"],
     "process:spawn": ["aquaman"],

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "aquaman-plugin",
-  "version": "0.9.2",
-  "description": "Credential isolation plugin for OpenClaw",
+  "version": "0.11.0",
+  "description": "Protect API keys and secrets for OpenClaw — credentials stay in your vault, never in the agent's memory",
   "type": "module",
   "scripts": {
     "build": "echo 'OpenClaw runs TypeScript directly - no build needed'",
@@ -18,21 +18,23 @@
     "security",
     "credentials",
     "vault",
-    "1password"
+    "1password",
+    "api-key",
+    "secrets",
+    "keychain",
+    "bitwarden",
+    "credential-isolation",
+    "token-security",
+    "api-protection"
   ],
   "author": "tech4242",
   "license": "MIT",
   "dependencies": {
-    "undici": "^7.0.0"
+    "undici": "^7.0.0",
+    "aquaman-proxy": "0.11.0"
   },
   "peerDependencies": {
-    "openclaw": ">=2026.1.11",
-    "aquaman-proxy": "0.9.2"
-  },
-  "peerDependenciesMeta": {
-    "aquaman-proxy": {
-      "optional": true
-    }
+    "openclaw": ">=2026.4.7"
   },
   "devDependencies": {
     "@types/node": "^20.10.0",

package/src/commands.ts

@@ -2,9 +2,13 @@
  * Slash commands for the OpenClaw plugin
  *
  * Provides /aquaman commands for users to interact with the plugin.
+ * Non-interactive commands execute the aquaman proxy binary directly.
+ * Interactive commands (add) show instructions since slash commands
+ * run in the chat UI where TTY is not available.
  */
 
 import type { ProxyManager } from './proxy-manager.js';
+import { execAquamanProxyCli, findAquamanProxyBinary } from './proxy-manager.js';
 import type { PluginConfig } from './config-schema.js';
 
 export interface CommandContext {
@@ -32,11 +36,13 @@ export interface PluginCommand {
  */
 export async function statusCommand(ctx: CommandContext): Promise<CommandResult> {
   const lines: string[] = [];
+  const cliInstalled = findAquamanProxyBinary() !== null;
 
   lines.push('aquaman plugin status');
   lines.push('');
   lines.push(`Backend: ${ctx.config.backend || 'keychain'}`);
   lines.push(`Services: ${(ctx.config.services || []).join(', ')}`);
+  lines.push(`Proxy binary: ${cliInstalled ? 'found' : 'NOT FOUND'}`);
 
   if (ctx.proxyManager?.isRunning()) {
     const info = ctx.proxyManager.getConnectionInfo();
@@ -46,6 +52,10 @@ export async function statusCommand(ctx: CommandContext): Promise<CommandResult>
   } else {
     lines.push('');
     lines.push('Proxy Status: Not running');
+    if (!cliInstalled) {
+      lines.push('');
+      lines.push('Setup: npm install -g aquaman-proxy && aquaman setup');
+    }
   }
 
   return {
@@ -55,7 +65,7 @@ export async function statusCommand(ctx: CommandContext): Promise<CommandResult>
 }
 
 /**
- * /aquaman add <service> - Add a credential (prompts for value)
+ * /aquaman add <service> - Add a credential (shows instructions — TTY not available in chat UI)
  */
 export async function addCommand(
   _ctx: CommandContext,
@@ -65,7 +75,8 @@ export async function addCommand(
   return {
     success: true,
     message: `To add a credential for ${service}/${key}:\n\n` +
-      `Run: aquaman credentials add ${service} ${key}\n\n` +
+      `Run: openclaw aquaman credentials add ${service} ${key}\n` +
+      `Or in terminal: aquaman credentials add ${service} ${key}\n\n` +
       `Or configure via environment variables:\n` +
       `  export AQUAMAN_${service.toUpperCase()}_${key.toUpperCase()}=<your-key>`
   };
@@ -75,30 +86,72 @@ export async function addCommand(
  * /aquaman list - List stored credentials
  */
 export async function listCommand(_ctx: CommandContext): Promise<CommandResult> {
-  return {
-    success: true,
-    message: 'Run in your terminal:\n  aquaman credentials list'
-  };
+  try {
+    const result = await execAquamanProxyCli(['credentials', 'list']);
+    return { success: result.exitCode === 0, message: result.stdout || result.stderr };
+  } catch (err: any) {
+    return { success: false, message: `Failed: ${err.message}\n\nRun in terminal: aquaman credentials list` };
+  }
+}
+
+/**
+ * /aquaman doctor - Run diagnostic checks
+ */
+export async function doctorCommand(_ctx: CommandContext): Promise<CommandResult> {
+  try {
+    const result = await execAquamanProxyCli(['doctor']);
+    return { success: result.exitCode === 0, message: result.stdout || result.stderr };
+  } catch (err: any) {
+    return { success: false, message: `Failed: ${err.message}\n\nRun in terminal: aquaman doctor` };
+  }
 }
 
 /**
  * /aquaman logs - Show recent audit entries
  */
-export async function logsCommand(_ctx: CommandContext, _count: number = 10): Promise<CommandResult> {
-  return {
-    success: true,
-    message: 'Run in your terminal:\n  aquaman audit tail'
-  };
+export async function logsCommand(_ctx: CommandContext, count: number = 10): Promise<CommandResult> {
+  try {
+    const result = await execAquamanProxyCli(['audit', 'tail', '-n', String(count)]);
+    return { success: result.exitCode === 0, message: result.stdout || result.stderr };
+  } catch (err: any) {
+    return { success: false, message: `Failed: ${err.message}\n\nRun in terminal: aquaman audit tail` };
+  }
 }
 
 /**
  * /aquaman verify - Verify audit log integrity
  */
 export async function verifyCommand(_ctx: CommandContext): Promise<CommandResult> {
-  return {
-    success: true,
-    message: 'Run in your terminal:\n  aquaman audit verify'
-  };
+  try {
+    const result = await execAquamanProxyCli(['audit', 'verify']);
+    return { success: result.exitCode === 0, message: result.stdout || result.stderr };
+  } catch (err: any) {
+    return { success: false, message: `Failed: ${err.message}\n\nRun in terminal: aquaman audit verify` };
+  }
+}
+
+/**
+ * /aquaman policy - List policy rules
+ */
+export async function policyListCommand(_ctx: CommandContext): Promise<CommandResult> {
+  try {
+    const result = await execAquamanProxyCli(['policy', 'list']);
+    return { success: result.exitCode === 0, message: result.stdout || result.stderr };
+  } catch (err: any) {
+    return { success: false, message: `Failed: ${err.message}\n\nRun in terminal: aquaman policy list` };
+  }
+}
+
+/**
+ * /aquaman services - List configured services
+ */
+export async function servicesListCommand(_ctx: CommandContext): Promise<CommandResult> {
+  try {
+    const result = await execAquamanProxyCli(['services', 'list']);
+    return { success: result.exitCode === 0, message: result.stdout || result.stderr };
+  } catch (err: any) {
+    return { success: false, message: `Failed: ${err.message}\n\nRun in terminal: aquaman services list` };
+  }
 }
 
 /**
@@ -122,6 +175,9 @@ export async function executeCommand(
     case 'list':
       return listCommand(ctx);
 
+    case 'doctor':
+      return doctorCommand(ctx);
+
     case 'logs': {
       const count = args[0] ? parseInt(args[0], 10) : 10;
       return logsCommand(ctx, count);
@@ -130,18 +186,37 @@ export async function executeCommand(
     case 'verify':
       return verifyCommand(ctx);
 
+    case 'policy':
+      return policyListCommand(ctx);
+
+    case 'services':
+      return servicesListCommand(ctx);
+
     case 'help':
     default:
       return {
         success: true,
         message: `aquaman plugin commands:
 
-  /aquaman status    - Show plugin status
-  /aquaman add       - Add a credential (shows instructions)
+  /aquaman status    - Show plugin and proxy status
+  /aquaman doctor    - Run diagnostic checks
+  /aquaman add       - Add a credential
   /aquaman list      - List stored credentials
+  /aquaman policy    - List request policy rules
+  /aquaman services  - List configured services
   /aquaman logs [n]  - Show recent audit entries
   /aquaman verify    - Verify audit log integrity
-  /aquaman help      - Show this help message`
+  /aquaman help      - Show this help message
+
+CLI commands (via terminal or openclaw aquaman <cmd>):
+
+  openclaw aquaman setup           - Run the setup wizard
+  openclaw aquaman doctor          - Diagnose issues
+  openclaw aquaman credentials list - List credentials
+  openclaw aquaman credentials add  - Add a credential (interactive)
+  openclaw aquaman policy-list     - Show policy rules
+  openclaw aquaman audit-tail      - Recent audit entries
+  openclaw aquaman services-list   - List services`
       };
   }
 }
@@ -180,6 +255,30 @@ export function getAvailableCommands(ctx: CommandContext): PluginCommand[] {
         return result.message;
       }
     },
+    {
+      name: 'doctor',
+      description: 'Run diagnostic checks',
+      execute: async () => {
+        const result = await doctorCommand(ctx);
+        return result.message;
+      }
+    },
+    {
+      name: 'policy',
+      description: 'List request policy rules',
+      execute: async () => {
+        const result = await policyListCommand(ctx);
+        return result.message;
+      }
+    },
+    {
+      name: 'services',
+      description: 'List configured services',
+      execute: async () => {
+        const result = await servicesListCommand(ctx);
+        return result.message;
+      }
+    },
     {
       name: 'logs',
       description: 'Show recent audit log entries',

package/src/proxy-manager.ts

@@ -9,8 +9,106 @@ import { spawn, type ChildProcess } from 'node:child_process';
 import * as path from 'node:path';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
+import { fileURLToPath } from 'node:url';
 import type { PluginConfig } from './config-schema.js';
 
+/**
+ * Find the aquaman proxy binary.
+ *
+ * Search order:
+ * 1. Plugin's own node_modules/.bin/aquaman (bundled dep — version-matched)
+ * 2. PATH (global install via npm install -g aquaman-proxy)
+ */
+export function findAquamanProxyBinary(): string | null {
+  // 1. Resolve from this file's location → plugin package root → node_modules/.bin/
+  const thisDir = path.dirname(fileURLToPath(import.meta.url));
+  const pluginRoot = path.resolve(thisDir, '..');
+  const localBin = path.join(pluginRoot, 'node_modules', '.bin', 'aquaman');
+  if (fs.existsSync(localBin)) {
+    return localBin;
+  }
+
+  // 2. Search PATH
+  const pathEnv = process.env.PATH || '';
+  const dirs = pathEnv.split(path.delimiter);
+  for (const dir of dirs) {
+    const candidate = path.join(dir, 'aquaman');
+    try {
+      fs.accessSync(candidate, fs.constants.X_OK);
+      return candidate;
+    } catch {
+      // Not found in this dir
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Execute an aquaman proxy CLI command (non-interactive).
+ * Captures stdout/stderr and returns them.
+ */
+export function execAquamanProxyCli(
+  args: string[],
+  options?: { timeoutMs?: number },
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  return new Promise((resolve, reject) => {
+    const binary = findAquamanProxyBinary();
+    if (!binary) {
+      reject(new Error('aquaman proxy binary not found. Install with: npm install -g aquaman-proxy'));
+      return;
+    }
+
+    const proc = spawn(binary, args, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: process.env,
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    proc.stdout?.on('data', (d: Buffer) => { stdout += d.toString(); });
+    proc.stderr?.on('data', (d: Buffer) => { stderr += d.toString(); });
+
+    proc.on('error', reject);
+    proc.on('close', (code) => {
+      resolve({ stdout, stderr, exitCode: code ?? 1 });
+    });
+
+    const timeout = options?.timeoutMs ?? 30_000;
+    const timer = setTimeout(() => {
+      proc.kill('SIGTERM');
+      reject(new Error(`aquaman CLI timed out after ${timeout}ms`));
+    }, timeout);
+
+    proc.on('close', () => clearTimeout(timer));
+  });
+}
+
+/**
+ * Execute an aquaman proxy CLI command interactively (stdio: inherit).
+ * Used for commands that need TTY input (setup, credentials add).
+ */
+export function execAquamanProxyInteractive(
+  args: string[],
+): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const binary = findAquamanProxyBinary();
+    if (!binary) {
+      reject(new Error('aquaman proxy binary not found. Install with: npm install -g aquaman-proxy'));
+      return;
+    }
+
+    const proc = spawn(binary, args, {
+      stdio: 'inherit',
+      env: process.env,
+    });
+
+    proc.on('error', reject);
+    proc.on('close', (code) => resolve(code ?? 1));
+  });
+}
+
 export interface ProxyConnectionInfo {
   ready: boolean;
   socketPath: string;
@@ -66,7 +164,7 @@ export class ProxyManager {
       const config = this.options.config;
 
       // Find aquaman binary
-      const binaryPath = this.findAquamanBinary();
+      const binaryPath = this.findBinary();
 
       if (!binaryPath) {
         const error = new Error(
@@ -199,45 +297,10 @@ export class ProxyManager {
   }
 
   /**
-   * Find the aquaman binary
+   * Find the aquaman proxy binary
    */
-  private findAquamanBinary(): string | null {
-    // Check common locations
-    const locations = [
-      // In node_modules
-      path.join(process.cwd(), 'node_modules', '.bin', 'aquaman'),
-      path.join(process.cwd(), 'node_modules', '@aquaman', 'proxy', 'dist', 'cli', 'index.js'),
-
-      // Global install
-      '/usr/local/bin/aquaman',
-
-      // In PATH (will use which in spawn)
-      'aquaman'
-    ];
-
-    for (const loc of locations) {
-      if (loc === 'aquaman') {
-        // Check if in PATH using filesystem checks (no shell execution)
-        const pathEnv = process.env.PATH || '';
-        const dirs = pathEnv.split(path.delimiter);
-        for (const dir of dirs) {
-          const candidate = path.join(dir, 'aquaman');
-          try {
-            fs.accessSync(candidate, fs.constants.X_OK);
-            return 'aquaman';
-          } catch {
-            // Not found in this dir
-          }
-        }
-        continue;
-      }
-
-      if (fs.existsSync(loc)) {
-        return loc;
-      }
-    }
-
-    return null;
+  private findBinary(): string | null {
+    return findAquamanProxyBinary();
   }
 }