@agentrux/agentrux-openclaw-plugin 0.3.2

package/README.md

@@ -0,0 +1,142 @@
+# AgenTrux Plugin for OpenClaw
+
+Connect your OpenClaw agent to other agents via AgenTrux — authenticated Pub/Sub for autonomous agents.
+
+**v0.3.1**: Now supports **Ingress mode** — external clients can send commands to OpenClaw via AgenTrux Topics and receive LLM-processed results back.
+
+## Install
+
+```bash
+openclaw plugins install @agentrux/agentrux-openclaw-plugin
+```
+
+## Quick Start
+
+### 1. Activate
+
+```
+OpenClaw> AgenTrux に接続して。activation code は ac_Abc123...
+
+  🔑 Activating...
+  ✅ Connected! Credentials saved.
+```
+
+### 2. Configure Ingress (optional)
+
+Add to your OpenClaw config (`plugins.entries.agentrux-openclaw-plugin.config`):
+
+```json
+{
+  "commandTopicId": "your-command-topic-uuid",
+  "resultTopicId": "your-result-topic-uuid",
+  "agentId": "agentrux-rpa",
+  "ingressMode": "sse",
+  "webhookSecret": "whsec_...",
+  "pollIntervalMs": 60000,
+  "maxConcurrency": 3,
+  "subagentTimeoutMs": 120000
+}
+```
+
+### 3. Send commands from anywhere
+
+```bash
+curl -X POST "https://api.agentrux.com/topics/{commandTopicId}/events" \
+  -H "Authorization: Bearer $JWT" \
+  -d '{"type":"openclaw.request","payload":{"request_id":"req-001","message":"Check disk usage"}}'
+```
+
+OpenClaw processes the request using its LLM + tools (exec, browser, etc.) and publishes the result to `resultTopicId`.
+
+## Tools (LLM-callable)
+
+| Tool | Description |
+|------|-------------|
+| `agentrux_activate` | Connect with a one-time activation code |
+| `agentrux_publish` | Send an event to a topic |
+| `agentrux_read` | Read events from a topic |
+| `agentrux_send_message` | Send a message and wait for reply |
+| `agentrux_redeem_grant` | Redeem an invite code for cross-account access |
+
+## Ingress Modes
+
+| Mode | How it works | When to use |
+|------|-------------|-------------|
+| `webhook` (default) | AgenTrux pushes hints to `/agentrux/webhook` | Public IP + HTTPS available |
+| `sse` | Plugin connects to AgenTrux SSE stream | No public IP (e.g. Spot VM, NAT) |
+
+Both modes include a **safety poller** (default 60s) as fallback for gap detection.
+
+## Message Format
+
+### Request (external → Topic)
+
+```json
+{
+  "type": "openclaw.request",
+  "payload": {
+    "request_id": "req-001",
+    "conversation_key": "user-42/session-1",
+    "message": "Check disk usage and report"
+  }
+}
+```
+
+### Response (OpenClaw → Topic)
+
+```json
+{
+  "type": "openclaw.response",
+  "payload": {
+    "request_id": "req-001",
+    "status": "completed",
+    "message": "Disk usage: /dev/root 49G 4.8G 44G 10%"
+  }
+}
+```
+
+## Architecture
+
+```
+External Client                         OpenClaw Gateway
+─────────────                           ────────────────
+publish(commandTopic,                   ┌─ Webhook / SSE (real-time hints)
+  {message: "check disk"})              │
+     │                                  ├─ Safety Poller (60s fallback)
+     ▼                                  │
+AgenTrux Topic ──────────────────→ Dispatcher
+                                        │
+                                        ▼
+                                   subagent.run() → LLM + Tools
+                                        │
+                                        ▼
+                                   Outbox → publish → Results Topic
+                                        │
+read(resultTopic) ←─────────────────────┘
+```
+
+## Reliability
+
+- **Waterline cursor**: Contiguous ack with in-flight tracking
+- **Outbox pattern**: Decouples agent completion from publish success
+- **Two-layer dedup**: event_id (transport) + request_id (application)
+- **Crash recovery**: In-flight events re-enqueued on restart
+- **Published history**: Retained for idempotency across restarts
+
+## Credentials
+
+Stored at `~/.agentrux/credentials.json` (permissions: 0600).
+
+| Credential | Lifetime | Storage |
+|---|---|---|
+| script_id + client_secret | Permanent | File |
+| JWT (access_token) | 1 hour | Memory (auto-refresh) |
+| Refresh token | Single-use | Memory (auto-rotate) |
+
+## Security
+
+- Webhook signature verification (HMAC-SHA256, constant-time compare)
+- `reply_topic` and `agent_id` fixed in config (not from request)
+- Prompt injection mitigation via message template wrapping
+- `sessionKey` hashed with topic scope
+- `execPolicy`: exec tool disabled by default, opt-in with command allowlist

package/dist/__tests__/naming.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Token naming correctness tests for the OpenClaw plugin.
+ *
+ * Verifies that the plugin uses the final unified naming:
+ * clientSecret, activation_code, inv_, ac_, api.agentrux.com.
+ * Ensures no legacy names (secret, token as activation param,
+ * process.env.HOME for credentials path) remain.
+ */
+export {};

package/dist/__tests__/naming.test.js

@@ -0,0 +1,143 @@
+"use strict";
+/**
+ * Token naming correctness tests for the OpenClaw plugin.
+ *
+ * Verifies that the plugin uses the final unified naming:
+ * clientSecret, activation_code, inv_, ac_, api.agentrux.com.
+ * Ensures no legacy names (secret, token as activation param,
+ * process.env.HOME for credentials path) remain.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+// We read the source file directly because the module's default export
+// is a function that registers tools on an api object — we need to
+// inspect both the static source text and the runtime registrations.
+const SOURCE_PATH = path.resolve(__dirname, "..", "index.ts");
+const source = fs.readFileSync(SOURCE_PATH, "utf-8");
+function captureTools() {
+    const tools = [];
+    const fakeApi = {
+        registerTool(def, _opts) {
+            tools.push(def);
+        },
+    };
+    // Import the default export and invoke it with our fake api.
+    // We need to isolate the module to avoid side effects from credential loading.
+    jest.isolateModules(() => {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const pluginModule = require("../index");
+        const register = pluginModule.default || pluginModule;
+        register(fakeApi);
+    });
+    return tools;
+}
+function findTool(tools, name) {
+    return tools.find((t) => t.name === name);
+}
+// ---------------------------------------------------------------------------
+// Credential interface
+// ---------------------------------------------------------------------------
+describe("Credentials interface", () => {
+    test("has clientSecret field (not secret)", () => {
+        // Check the Credentials interface definition in source
+        expect(source).toContain("clientSecret: string");
+        // Must not have a bare "secret: string" field in the interface
+        expect(source).not.toMatch(/^\s+secret:\s+string/m);
+    });
+});
+// ---------------------------------------------------------------------------
+// Activate tool parameter naming
+// ---------------------------------------------------------------------------
+describe("Activate tool", () => {
+    let tools;
+    let activateTool;
+    beforeAll(() => {
+        tools = captureTools();
+        activateTool = findTool(tools, "agentrux_activate");
+    });
+    test("activate tool exists", () => {
+        expect(activateTool).toBeDefined();
+    });
+    test("parameter is activation_code (not token)", () => {
+        const props = activateTool.parameters.properties;
+        expect(props).toHaveProperty("activation_code");
+        // "token" should not be the parameter name for activation
+        expect(props).not.toHaveProperty("activation_token");
+    });
+    test("activation_code description references ac_ prefix", () => {
+        const desc = activateTool.parameters.properties.activation_code.description;
+        expect(desc).toContain("ac_");
+        expect(desc).not.toContain("atk_");
+    });
+});
+// ---------------------------------------------------------------------------
+// Default base URL
+// ---------------------------------------------------------------------------
+describe("Default base URL", () => {
+    test("default is https://api.agentrux.com", () => {
+        // Check the source for the default base_url assignment
+        expect(source).toContain("https://api.agentrux.com");
+        expect(source).not.toContain("example.com");
+    });
+});
+// ---------------------------------------------------------------------------
+// Credentials path
+// ---------------------------------------------------------------------------
+describe("Credentials path", () => {
+    test("does NOT use process.env.HOME", () => {
+        expect(source).not.toContain("process.env.HOME");
+    });
+    test("uses .agentrux directory", () => {
+        expect(source).toContain(".agentrux");
+    });
+});
+// ---------------------------------------------------------------------------
+// No legacy names in source
+// ---------------------------------------------------------------------------
+describe("No legacy names in source", () => {
+    test("no old token prefixes", () => {
+        expect(source).not.toContain("atk_");
+        expect(source).not.toContain("gtk_");
+    });
+    test("no old placeholder domains", () => {
+        expect(source).not.toContain("example.com");
+        expect(source).not.toContain("your-org");
+    });
+    test("invite code uses inv_ prefix", () => {
+        expect(source).toContain("inv_");
+    });
+});

package/dist/credentials.d.ts

@@ -0,0 +1,11 @@
+/**
+ * AgenTrux credential management.
+ * Credentials persisted to ~/.agentrux/credentials.json (0600).
+ */
+export interface Credentials {
+    base_url: string;
+    script_id: string;
+    clientSecret: string;
+}
+export declare function loadCredentials(): Credentials | null;
+export declare function saveCredentials(creds: Credentials): void;

package/dist/credentials.js

@@ -0,0 +1,63 @@
+"use strict";
+/**
+ * AgenTrux credential management.
+ * Credentials persisted to ~/.agentrux/credentials.json (0600).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadCredentials = loadCredentials;
+exports.saveCredentials = saveCredentials;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const HOME = process.env.HOME || process.env.USERPROFILE || "~";
+const CREDENTIALS_DIR = path.join(HOME, ".agentrux");
+const CREDENTIALS_PATH = path.join(CREDENTIALS_DIR, "credentials.json");
+function loadCredentials() {
+    try {
+        if (fs.existsSync(CREDENTIALS_PATH)) {
+            return JSON.parse(fs.readFileSync(CREDENTIALS_PATH, "utf-8"));
+        }
+    }
+    catch { }
+    return null;
+}
+function saveCredentials(creds) {
+    if (!fs.existsSync(CREDENTIALS_DIR)) {
+        fs.mkdirSync(CREDENTIALS_DIR, { recursive: true, mode: 0o700 });
+    }
+    fs.writeFileSync(CREDENTIALS_PATH, JSON.stringify(creds, null, 2), {
+        mode: 0o600,
+    });
+}

package/dist/cursor.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Waterline cursor with atomic persistence.
+ * Tracks: waterline (contiguous ack), inFlight, completed, processedEvents.
+ */
+export interface CursorState {
+    version: number;
+    waterline: number;
+    inFlight: Set<number>;
+    completed: Set<number>;
+    processedEvents: Map<string, number>;
+}
+export declare function createEmptyCursor(): CursorState;
+export declare function loadCursor(): CursorState;
+export declare function persistCursor(state: CursorState): void;
+export declare function markInFlight(state: CursorState, seq: number): void;
+export declare function markCompleted(state: CursorState, seq: number): void;
+/**
+ * Mark as completed for waterline purposes (used for dead_letter too).
+ * Dead letter items are treated as completed to avoid head-of-line blocking.
+ */
+export declare function markDeadLetter(state: CursorState, seq: number): void;
+export declare function advanceWaterline(state: CursorState): void;
+export declare function isEventProcessed(state: CursorState, eventId: string): boolean;
+export declare function recordProcessedEvent(state: CursorState, eventId: string): void;
+export declare function cleanupExpiredEvents(state: CursorState): void;

package/dist/cursor.js

@@ -0,0 +1,144 @@
+"use strict";
+/**
+ * Waterline cursor with atomic persistence.
+ * Tracks: waterline (contiguous ack), inFlight, completed, processedEvents.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEmptyCursor = createEmptyCursor;
+exports.loadCursor = loadCursor;
+exports.persistCursor = persistCursor;
+exports.markInFlight = markInFlight;
+exports.markCompleted = markCompleted;
+exports.markDeadLetter = markDeadLetter;
+exports.advanceWaterline = advanceWaterline;
+exports.isEventProcessed = isEventProcessed;
+exports.recordProcessedEvent = recordProcessedEvent;
+exports.cleanupExpiredEvents = cleanupExpiredEvents;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const HOME = process.env.HOME || process.env.USERPROFILE || "~";
+const CURSOR_PATH = path.join(HOME, ".agentrux", "cursor.json");
+const MAX_PROCESSED_EVENTS = 10_000;
+const EVENT_TTL_MS = 24 * 60 * 60 * 1000; // 24h
+function createEmptyCursor() {
+    return {
+        version: 1,
+        waterline: 0,
+        inFlight: new Set(),
+        completed: new Set(),
+        processedEvents: new Map(),
+    };
+}
+function loadCursor() {
+    try {
+        if (fs.existsSync(CURSOR_PATH)) {
+            const raw = JSON.parse(fs.readFileSync(CURSOR_PATH, "utf-8"));
+            return {
+                version: raw.version || 1,
+                waterline: raw.waterline || 0,
+                inFlight: new Set(raw.inFlight || []),
+                completed: new Set(raw.completed || []),
+                processedEvents: new Map(Object.entries(raw.processedEvents || {})),
+            };
+        }
+    }
+    catch { }
+    return createEmptyCursor();
+}
+function persistCursor(state) {
+    const dir = path.dirname(CURSOR_PATH);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    const data = JSON.stringify({
+        version: state.version,
+        waterline: state.waterline,
+        inFlight: [...state.inFlight],
+        completed: [...state.completed],
+        processedEvents: Object.fromEntries(state.processedEvents),
+    }, null, 2);
+    // Atomic write: temp → fsync → rename
+    const tmpPath = CURSOR_PATH + ".tmp." + process.pid;
+    fs.writeFileSync(tmpPath, data, { mode: 0o600 });
+    fs.fsyncSync(fs.openSync(tmpPath, "r"));
+    fs.renameSync(tmpPath, CURSOR_PATH);
+}
+function markInFlight(state, seq) {
+    state.inFlight.add(seq);
+}
+function markCompleted(state, seq) {
+    state.inFlight.delete(seq);
+    state.completed.add(seq);
+    advanceWaterline(state);
+}
+/**
+ * Mark as completed for waterline purposes (used for dead_letter too).
+ * Dead letter items are treated as completed to avoid head-of-line blocking.
+ */
+function markDeadLetter(state, seq) {
+    markCompleted(state, seq);
+}
+function advanceWaterline(state) {
+    while (state.completed.has(state.waterline + 1)) {
+        state.waterline++;
+        state.completed.delete(state.waterline);
+        state.inFlight.delete(state.waterline);
+    }
+    persistCursor(state);
+}
+function isEventProcessed(state, eventId) {
+    return state.processedEvents.has(eventId);
+}
+function recordProcessedEvent(state, eventId) {
+    state.processedEvents.set(eventId, Date.now());
+}
+function cleanupExpiredEvents(state) {
+    const now = Date.now();
+    for (const [id, ts] of state.processedEvents) {
+        if (now - ts > EVENT_TTL_MS) {
+            state.processedEvents.delete(id);
+        }
+    }
+    // Cap size
+    if (state.processedEvents.size > MAX_PROCESSED_EVENTS) {
+        const entries = [...state.processedEvents.entries()]
+            .sort((a, b) => a[1] - b[1]);
+        const toRemove = entries.slice(0, entries.length - MAX_PROCESSED_EVENTS);
+        for (const [id] of toRemove) {
+            state.processedEvents.delete(id);
+        }
+    }
+}

package/dist/dispatcher.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Dispatcher: async loop.
+ * Consumes queue → Pull → dedup → subagent.run() → outbox → waterline.
+ */
+import { type Credentials } from "./credentials";
+import { type BoundedQueue } from "./queue";
+import { type CursorState } from "./cursor";
+export interface DispatcherConfig {
+    commandTopicId: string;
+    resultTopicId: string;
+    agentId: string;
+    maxConcurrency: number;
+    subagentTimeoutMs: number;
+    gatewayPort: number;
+}
+export declare class Dispatcher {
+    private config;
+    private creds;
+    private cursor;
+    private queue;
+    private logger;
+    private running;
+    private stopped;
+    private processedRequestIds;
+    private processingSeqs;
+    private statusPublished;
+    constructor(config: DispatcherConfig, creds: Credentials, cursor: CursorState, queue: BoundedQueue, logger: {
+        info: (...a: any[]) => void;
+        error: (...a: any[]) => void;
+        warn: (...a: any[]) => void;
+    });
+    start(): Promise<void>;
+    stop(): void;
+    private loop;
+    private tick;
+    private processEvent;
+    private callDispatchEndpoint;
+}