@moltenbot/openclaw-plugin-statocyst 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Molten.Bot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,100 @@
+# @moltenbot/openclaw-plugin-statocyst
+
+OpenClaw plugin for realtime Statocyst skill execution messaging.
+
+This package is built and maintained by [Molten AI](https://molten.bot).
+
+## What this plugin adds
+
+- `statocyst_skill_request`: send a `skill_request` envelope to a trusted peer and wait for the matching `skill_result`
+- `statocyst_session_status`: verify websocket session health for the current plugin session
+- dedicated realtime websocket transport via Statocyst `/v1/openclaw/messages/ws`
+- explicit plugin registration and usage activity tracking in Statocyst profile metadata and agent activity log
+
+## Requirements
+
+- Node.js `>=22`
+- OpenClaw with plugin support enabled
+- A Statocyst agent token with trust established to the target peer agent
+
+## Install
+
+```bash
+openclaw plugins install @moltenbot/openclaw-plugin-statocyst
+openclaw gateway restart
+```
+
+## Configure
+
+Set plugin config under `plugins.entries.statocyst-openclaw.config`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "statocyst-openclaw": {
+        "enabled": true,
+        "config": {
+          "baseUrl": "https://hub.example.com/v1",
+          "token": "statocyst-agent-bearer-token",
+          "sessionKey": "main",
+          "timeoutMs": 20000
+        }
+      }
+    }
+  }
+}
+```
+
+Config fields:
+
+- `baseUrl` (required): Statocyst API base, including `/v1`
+- `token` (required): Statocyst bearer token for the current OpenClaw agent
+- `sessionKey` (optional, default `main`): dedicated realtime session key
+- `timeoutMs` (optional, default `20000`, max `60000`): tool request timeout
+
+## Statocyst usage registration
+
+This plugin actively records usage in Statocyst:
+
+- `POST /v1/openclaw/messages/register-plugin` is called before session checks and skill requests.
+- Statocyst stores plugin metadata on the agent profile under `metadata.plugins.statocyst-openclaw`.
+- Statocyst appends agent activity entries for:
+  - plugin registration (`openclaw_plugin`)
+  - OpenClaw adapter usage (`openclaw_adapter` events across publish/pull/ack/nack/status/ws)
+
+You can inspect this data via `GET /v1/agents/me`.
+
+## OpenClaw onboarding flow
+
+1. Create/bind the Statocyst agent token (`POST /v1/agents/bind-tokens`, then `POST /v1/agents/bind`).
+2. Configure plugin entry in OpenClaw (`plugins.entries.statocyst-openclaw.config`).
+3. Ensure your tool policy allows plugin tools:
+   - allow `statocyst_skill_request` and `statocyst_session_status` (or allow the plugin id).
+4. Restart OpenClaw gateway.
+5. Run `statocyst_session_status` once to validate connectivity.
+
+## Distribution and discovery checklist
+
+To maximize adoption and visibility:
+
+1. Publish this package to npm (`@moltenbot/openclaw-plugin-statocyst`).
+2. Publish to ClawHub (preferred by OpenClaw resolver).
+3. Keep a public GitHub repo with docs and issue tracker.
+4. Submit a PR to OpenClaw Community Plugins docs with:
+   - plugin name
+   - npm package
+   - GitHub URL
+   - one-line description
+   - install command
+5. Track in-product usage via Statocyst metadata/activity logs as described above.
+
+## Development
+
+```bash
+npm ci
+npm run build
+npm run test:coverage
+docker build -t statocyst-openclaw-e2e:local ../statocyst
+STATOCYST_IMAGE=statocyst-openclaw-e2e:local npm run test:e2e:container
+```

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { createStatocystOpenClawPlugin } from "./plugin.js";
+export { createStatocystOpenClawPlugin };
+export { resolveConfig, StatocystClient } from "./statocyst-client.js";
+export type { OpenClawPlugin, OpenClawPluginAPI, OpenClawToolRegisterOptions, ResolveConfigInput, OpenClawToolDefinition, SkillExecutionRequest, SkillExecutionResult, StatocystPluginConfig } from "./types.js";
+declare const plugin: import("./types.js").OpenClawPlugin;
+export default plugin;

package/dist/index.js

@@ -0,0 +1,5 @@
+import { createStatocystOpenClawPlugin } from "./plugin.js";
+export { createStatocystOpenClawPlugin };
+export { resolveConfig, StatocystClient } from "./statocyst-client.js";
+const plugin = createStatocystOpenClawPlugin();
+export default plugin;

package/dist/plugin.d.ts

@@ -0,0 +1,14 @@
+import type { OpenClawPlugin, SkillExecutionRequest, SkillExecutionResult, StatocystPluginConfig } from "./types.js";
+interface StatocystClientContract {
+    checkSession: () => Promise<{
+        status: string;
+        sessionKey: string;
+        transport: string;
+    }>;
+    requestSkillExecution: (request: SkillExecutionRequest) => Promise<SkillExecutionResult>;
+}
+export interface PluginFactoryDeps {
+    createClient?: (config: StatocystPluginConfig) => StatocystClientContract;
+}
+export declare function createStatocystOpenClawPlugin(deps?: PluginFactoryDeps): OpenClawPlugin;
+export {};

package/dist/plugin.js

@@ -0,0 +1,143 @@
+import { resolveConfig, StatocystClient } from "./statocyst-client.js";
+const skillRequestInputSchema = {
+    type: "object",
+    required: ["skillName"],
+    properties: {
+        toAgentUUID: {
+            type: "string",
+            description: "Target receiver agent UUID"
+        },
+        toAgentURI: {
+            type: "string",
+            description: "Target receiver canonical agent URI"
+        },
+        skillName: {
+            type: "string",
+            description: "Peer advertised skill name to execute"
+        },
+        input: {
+            description: "Skill input payload"
+        },
+        timeoutMs: {
+            type: "number",
+            description: "Override timeout for this request"
+        },
+        sessionKey: {
+            type: "string",
+            description: "Override dedicated session key"
+        },
+        requestId: {
+            type: "string",
+            description: "Optional caller-provided correlation id"
+        }
+    }
+};
+const sessionStatusInputSchema = {
+    type: "object",
+    properties: {}
+};
+function parseSkillExecutionRequest(input) {
+    return {
+        toAgentUUID: asTrimmedString(input.toAgentUUID),
+        toAgentURI: asTrimmedString(input.toAgentURI),
+        skillName: asTrimmedString(input.skillName) ?? "",
+        input: input.input,
+        timeoutMs: asNumber(input.timeoutMs),
+        sessionKey: asTrimmedString(input.sessionKey),
+        requestId: asTrimmedString(input.requestId)
+    };
+}
+function asTrimmedString(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    return trimmed;
+}
+function asNumber(value) {
+    if (typeof value !== "number") {
+        return undefined;
+    }
+    if (!Number.isFinite(value)) {
+        return undefined;
+    }
+    return value;
+}
+function asRecord(value) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        return value;
+    }
+    return {};
+}
+function asEnvMap(env) {
+    return {
+        ...process.env,
+        ...(env ?? {})
+    };
+}
+function formatToolText(payload) {
+    try {
+        return JSON.stringify(payload);
+    }
+    catch {
+        return String(payload);
+    }
+}
+function toToolResult(payload) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: formatToolText(payload)
+            }
+        ],
+        data: payload
+    };
+}
+function skillRequestTool(client) {
+    return {
+        name: "statocyst_skill_request",
+        description: "Send a Statocyst skill_request envelope to a peer and wait for the corresponding skill_result over the realtime websocket bus.",
+        parameters: skillRequestInputSchema,
+        execute: async (_callID, params) => {
+            const request = parseSkillExecutionRequest(asRecord(params));
+            const result = await client().requestSkillExecution(request);
+            return toToolResult(result);
+        }
+    };
+}
+function sessionStatusTool(client) {
+    return {
+        name: "statocyst_session_status",
+        description: "Check Statocyst realtime websocket connectivity for this plugin session.",
+        parameters: sessionStatusInputSchema,
+        execute: async () => {
+            const result = await client().checkSession();
+            return toToolResult(result);
+        }
+    };
+}
+function buildClient(api, factory) {
+    const config = resolveConfig({
+        config: api.pluginConfig ?? {},
+        env: asEnvMap(api.env)
+    });
+    return factory(config);
+}
+export function createStatocystOpenClawPlugin(deps) {
+    const factory = deps?.createClient ?? ((config) => new StatocystClient(config));
+    return {
+        id: "statocyst-openclaw",
+        name: "Statocyst Realtime",
+        description: "Molten AI maintained plugin for realtime skill request/result exchange via Statocyst.",
+        version: "0.1.0",
+        register: (api) => {
+            const client = buildClient(api, factory);
+            api.registerTool(skillRequestTool(() => client));
+            api.registerTool(sessionStatusTool(() => client));
+        }
+    };
+}

package/dist/statocyst-client.d.ts

@@ -0,0 +1,30 @@
+import type { ResolveConfigInput, SkillExecutionRequest, SkillExecutionResult, StatocystPluginConfig } from "./types.js";
+export interface WebSocketLike {
+    on: (event: string, listener: (...args: unknown[]) => void) => WebSocketLike;
+    send: (data: string, callback?: (error?: Error) => void) => void;
+    close: (code?: number) => void;
+}
+export type WebSocketFactory = (url: string, headers: Record<string, string>) => WebSocketLike;
+export interface StatocystClientDeps {
+    fetchImpl: typeof fetch;
+    wsFactory: WebSocketFactory;
+    now: () => Date;
+    randomID: () => string;
+}
+export declare class StatocystClient {
+    private readonly config;
+    private readonly deps;
+    constructor(config: StatocystPluginConfig, deps?: Partial<StatocystClientDeps>);
+    registerPlugin(): Promise<void>;
+    checkSession(): Promise<{
+        status: string;
+        sessionKey: string;
+        transport: string;
+    }>;
+    requestSkillExecution(request: SkillExecutionRequest): Promise<SkillExecutionResult>;
+    private openSession;
+    private waitForResponse;
+    private ackDelivery;
+    private nackDelivery;
+}
+export declare function resolveConfig(context: ResolveConfigInput): StatocystPluginConfig;

package/dist/statocyst-client.js

@@ -0,0 +1,421 @@
+import { randomUUID } from "node:crypto";
+import WebSocket from "ws";
+const defaultTimeoutMs = 20_000;
+const defaultPluginID = "statocyst-openclaw";
+const defaultPluginPackage = "@moltenbot/openclaw-plugin-statocyst";
+const defaultPluginVersion = "0.1.0";
+const defaultDeps = {
+    fetchImpl: fetch,
+    wsFactory: (url, headers) => new WebSocket(url, { headers }),
+    now: () => new Date(),
+    randomID: () => randomUUID()
+};
+class MessageQueue {
+    queue = [];
+    pending = [];
+    push(message) {
+        if (this.pending.length > 0) {
+            const resolver = this.pending.shift();
+            if (resolver) {
+                resolver(message);
+            }
+            return;
+        }
+        this.queue.push(message);
+    }
+    next(timeoutMs) {
+        if (this.queue.length > 0) {
+            const message = this.queue.shift();
+            if (message) {
+                return Promise.resolve(message);
+            }
+        }
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending = this.pending.filter((fn) => fn !== resolver);
+                reject(new Error(`timed out waiting for websocket message after ${timeoutMs}ms`));
+            }, timeoutMs);
+            const resolver = (message) => {
+                clearTimeout(timer);
+                resolve(message);
+            };
+            this.pending.push(resolver);
+        });
+    }
+}
+class WebSocketSession {
+    socket;
+    queue = new MessageQueue();
+    constructor(socket) {
+        this.socket = socket;
+    }
+    attach() {
+        this.socket.on("message", (raw) => {
+            this.queue.push(parseWSMessage(raw));
+        });
+        this.socket.on("error", (error) => {
+            this.queue.push({
+                type: "__error__",
+                error: String(error)
+            });
+        });
+        this.socket.on("close", () => {
+            this.queue.push({ type: "__close__" });
+        });
+    }
+    async send(payload) {
+        await new Promise((resolve, reject) => {
+            this.socket.send(JSON.stringify(payload), (error) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+                resolve();
+            });
+        });
+    }
+    async next(timeoutMs) {
+        return this.queue.next(timeoutMs);
+    }
+    close() {
+        this.socket.close(1000);
+    }
+}
+export class StatocystClient {
+    config;
+    deps;
+    constructor(config, deps) {
+        this.config = config;
+        this.deps = {
+            ...defaultDeps,
+            ...deps
+        };
+    }
+    async registerPlugin() {
+        const response = await this.deps.fetchImpl(`${this.config.baseUrl}/openclaw/messages/register-plugin`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${this.config.token}`
+            },
+            body: JSON.stringify({
+                plugin_id: this.config.pluginId,
+                package: this.config.pluginPackage,
+                version: this.config.pluginVersion,
+                transport: "websocket",
+                session_mode: "dedicated",
+                session_key: this.config.sessionKey
+            })
+        });
+        if (!response.ok) {
+            const body = await safeReadText(response);
+            throw new Error(`statocyst plugin registration failed (${response.status}): ${body}`);
+        }
+    }
+    async checkSession() {
+        await this.registerPlugin();
+        const session = await this.openSession(this.config.sessionKey, this.config.timeoutMs);
+        try {
+            return {
+                status: "ok",
+                sessionKey: this.config.sessionKey,
+                transport: "websocket"
+            };
+        }
+        finally {
+            session.close();
+        }
+    }
+    async requestSkillExecution(request) {
+        const targetUUID = trimOrEmpty(request.toAgentUUID);
+        const targetURI = trimOrEmpty(request.toAgentURI);
+        const skillName = trimOrEmpty(request.skillName);
+        if (!targetUUID && !targetURI) {
+            throw new Error("toAgentUUID or toAgentURI is required");
+        }
+        if (!skillName) {
+            throw new Error("skillName is required");
+        }
+        const timeoutMs = normalizeTimeout(request.timeoutMs ?? this.config.timeoutMs);
+        const requestId = trimOrEmpty(request.requestId) || this.deps.randomID();
+        const sessionKey = trimOrEmpty(request.sessionKey) || this.config.sessionKey;
+        await this.registerPlugin();
+        const session = await this.openSession(sessionKey, timeoutMs);
+        try {
+            const publishRequestID = `publish:${requestId}`;
+            await session.send({
+                type: "publish",
+                request_id: publishRequestID,
+                to_agent_uuid: targetUUID || undefined,
+                to_agent_uri: targetURI || undefined,
+                message: {
+                    kind: "skill_request",
+                    request_id: requestId,
+                    skill_name: skillName,
+                    reply_required: true,
+                    input: request.input,
+                    session_key: sessionKey,
+                    timestamp: this.deps.now().toISOString()
+                }
+            });
+            await this.waitForResponse(session, publishRequestID, timeoutMs);
+            const deadline = Date.now() + timeoutMs;
+            for (;;) {
+                const remaining = deadline - Date.now();
+                const waitMs = Math.max(1, remaining);
+                let payload;
+                try {
+                    payload = await session.next(waitMs);
+                }
+                catch {
+                    throw new Error(`timed out waiting for skill_result for request_id=${requestId}`);
+                }
+                const payloadType = trimOrEmpty(payload.type);
+                if (payloadType === "__error__") {
+                    throw new Error(`websocket error: ${trimOrEmpty(payload.error)}`);
+                }
+                if (payloadType === "__close__") {
+                    throw new Error("websocket session closed");
+                }
+                if (payloadType === "delivery") {
+                    const message = readObject(readObject(payload.result).openclaw_message);
+                    const deliveryID = trimOrEmpty(readObject(readObject(payload.result).delivery).delivery_id);
+                    const messageID = trimOrEmpty(readObject(readObject(payload.result).message).message_id);
+                    const kind = trimOrEmpty(message.kind);
+                    const resultRequestID = trimOrEmpty(message.request_id);
+                    if (kind === "skill_result" && resultRequestID === requestId) {
+                        await this.ackDelivery(session, deliveryID, timeoutMs);
+                        return {
+                            requestId,
+                            skillName,
+                            status: trimOrEmpty(message.status) || "ok",
+                            output: message.output,
+                            error: message.error,
+                            messageId: messageID,
+                            deliveryId: deliveryID
+                        };
+                    }
+                    if (deliveryID) {
+                        await this.nackDelivery(session, deliveryID);
+                    }
+                    continue;
+                }
+                if (payloadType === "response") {
+                    const ok = Boolean(payload.ok);
+                    if (!ok) {
+                        const code = trimOrEmpty(readObject(payload.error).code) || "unknown_error";
+                        const message = trimOrEmpty(readObject(payload.error).message) || "unknown error";
+                        throw new Error(`statocyst websocket response error (${code}): ${message}`);
+                    }
+                }
+            }
+        }
+        finally {
+            session.close();
+        }
+    }
+    async openSession(sessionKey, timeoutMs) {
+        const wsBase = this.config.baseUrl.replace(/^http/i, "ws");
+        const wsURL = `${wsBase}/openclaw/messages/ws?session_key=${encodeURIComponent(sessionKey)}`;
+        const socket = this.deps.wsFactory(wsURL, {
+            Authorization: `Bearer ${this.config.token}`
+        });
+        await waitForOpen(socket, timeoutMs);
+        const session = new WebSocketSession(socket);
+        session.attach();
+        const firstMessage = await session.next(timeoutMs);
+        if (trimOrEmpty(firstMessage.type) !== "session_ready") {
+            throw new Error(`unexpected websocket handshake message type=${trimOrEmpty(firstMessage.type)}`);
+        }
+        return session;
+    }
+    async waitForResponse(session, requestID, timeoutMs) {
+        const deadline = Date.now() + timeoutMs;
+        for (;;) {
+            const remaining = deadline - Date.now();
+            const waitMs = Math.max(1, remaining);
+            let payload;
+            try {
+                payload = await session.next(waitMs);
+            }
+            catch {
+                throw new Error(`timed out waiting for websocket response request_id=${requestID}`);
+            }
+            if (trimOrEmpty(payload.type) === "__error__") {
+                throw new Error(`websocket error: ${trimOrEmpty(payload.error)}`);
+            }
+            if (trimOrEmpty(payload.type) === "__close__") {
+                throw new Error("websocket session closed");
+            }
+            if (trimOrEmpty(payload.type) !== "response") {
+                if (trimOrEmpty(payload.type) === "delivery") {
+                    const deliveryID = trimOrEmpty(readObject(readObject(payload.result).delivery).delivery_id);
+                    if (deliveryID) {
+                        await this.nackDelivery(session, deliveryID);
+                    }
+                }
+                continue;
+            }
+            if (trimOrEmpty(payload.request_id) !== requestID) {
+                continue;
+            }
+            if (!Boolean(payload.ok)) {
+                const code = trimOrEmpty(readObject(payload.error).code) || "unknown_error";
+                const message = trimOrEmpty(readObject(payload.error).message) || "unknown error";
+                throw new Error(`statocyst websocket response error (${code}): ${message}`);
+            }
+            return;
+        }
+    }
+    async ackDelivery(session, deliveryID, timeoutMs) {
+        if (!deliveryID) {
+            return;
+        }
+        const requestID = `ack:${deliveryID}`;
+        await session.send({
+            type: "ack",
+            request_id: requestID,
+            delivery_id: deliveryID
+        });
+        await this.waitForResponse(session, requestID, timeoutMs);
+    }
+    async nackDelivery(session, deliveryID) {
+        await session.send({
+            type: "nack",
+            request_id: `nack:${deliveryID}`,
+            delivery_id: deliveryID
+        });
+    }
+}
+export function resolveConfig(context) {
+    const config = context.config ?? {};
+    const env = context.env ?? {};
+    const baseUrl = normalizeBaseURL(asString(config.baseUrl) ||
+        asString(config.baseURL) ||
+        env.STATOCYST_BASE_URL ||
+        env.STATOCYST_API_BASE ||
+        "");
+    const token = trimOrEmpty(asString(config.token) || env.STATOCYST_AGENT_TOKEN || "");
+    const sessionKey = trimOrEmpty(asString(config.sessionKey) || env.STATOCYST_SESSION_KEY || "main");
+    const timeoutMs = normalizeTimeout(asNumber(config.timeoutMs) ?? asNumber(env.STATOCYST_TIMEOUT_MS) ?? defaultTimeoutMs);
+    const pluginId = trimOrEmpty(asString(config.pluginId) || defaultPluginID);
+    const pluginPackage = trimOrEmpty(asString(config.pluginPackage) || defaultPluginPackage);
+    const pluginVersion = trimOrEmpty(asString(config.pluginVersion) || defaultPluginVersion);
+    if (!baseUrl) {
+        throw new Error("Statocyst plugin configuration requires baseUrl");
+    }
+    if (!token) {
+        throw new Error("Statocyst plugin configuration requires token");
+    }
+    return {
+        baseUrl,
+        token,
+        sessionKey,
+        timeoutMs,
+        pluginId,
+        pluginPackage,
+        pluginVersion
+    };
+}
+function waitForOpen(socket, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new Error(`timed out waiting for websocket open after ${timeoutMs}ms`));
+        }, timeoutMs);
+        socket.on("open", () => {
+            clearTimeout(timer);
+            resolve();
+        });
+        socket.on("error", (error) => {
+            clearTimeout(timer);
+            reject(new Error(String(error)));
+        });
+    });
+}
+function parseWSMessage(raw) {
+    try {
+        const value = normalizeWSRawData(raw);
+        if (!value) {
+            return { type: "__invalid__", raw: "" };
+        }
+        const decoded = JSON.parse(value);
+        if (decoded && typeof decoded === "object") {
+            return decoded;
+        }
+        return { type: "__invalid__", raw: value };
+    }
+    catch {
+        return { type: "__invalid__", raw: String(raw) };
+    }
+}
+function normalizeWSRawData(raw) {
+    if (typeof raw === "string") {
+        return raw;
+    }
+    if (raw instanceof ArrayBuffer) {
+        return Buffer.from(raw).toString("utf8");
+    }
+    if (Buffer.isBuffer(raw)) {
+        return raw.toString("utf8");
+    }
+    const maybeWSRaw = raw;
+    if (Array.isArray(maybeWSRaw)) {
+        return Buffer.concat(maybeWSRaw).toString("utf8");
+    }
+    return String(raw ?? "");
+}
+function normalizeBaseURL(raw) {
+    const trimmed = trimOrEmpty(raw);
+    if (!trimmed) {
+        return "";
+    }
+    return trimmed.replace(/\/+$/, "");
+}
+function normalizeTimeout(raw) {
+    if (!Number.isFinite(raw) || raw <= 0) {
+        return defaultTimeoutMs;
+    }
+    if (raw > 60_000) {
+        return 60_000;
+    }
+    return Math.trunc(raw);
+}
+function trimOrEmpty(value) {
+    if (typeof value !== "string") {
+        return "";
+    }
+    return value.trim();
+}
+function asString(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    return "";
+}
+function asNumber(value) {
+    if (typeof value === "number") {
+        return value;
+    }
+    if (typeof value === "string") {
+        const parsed = Number.parseInt(value, 10);
+        if (Number.isNaN(parsed)) {
+            return undefined;
+        }
+        return parsed;
+    }
+    return undefined;
+}
+function readObject(value) {
+    if (value && typeof value === "object") {
+        return value;
+    }
+    return {};
+}
+async function safeReadText(response) {
+    try {
+        return (await response.text()).trim();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,52 @@
+export interface OpenClawToolDefinition {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    execute: (callID: string, params: Record<string, unknown>) => Promise<unknown>;
+}
+export interface OpenClawToolRegisterOptions {
+    optional?: boolean;
+}
+export interface OpenClawPluginAPI {
+    registerTool: (tool: OpenClawToolDefinition, options?: OpenClawToolRegisterOptions) => void;
+    pluginConfig?: Record<string, unknown>;
+    env?: Record<string, string | undefined>;
+}
+export interface OpenClawPlugin {
+    id: string;
+    name: string;
+    description: string;
+    version: string;
+    register: (api: OpenClawPluginAPI) => void;
+}
+export interface ResolveConfigInput {
+    config?: Record<string, unknown>;
+    env?: Record<string, string | undefined>;
+}
+export interface StatocystPluginConfig {
+    baseUrl: string;
+    token: string;
+    sessionKey: string;
+    timeoutMs: number;
+    pluginId: string;
+    pluginPackage: string;
+    pluginVersion: string;
+}
+export interface SkillExecutionRequest {
+    toAgentUUID?: string;
+    toAgentURI?: string;
+    skillName: string;
+    input?: unknown;
+    timeoutMs?: number;
+    sessionKey?: string;
+    requestId?: string;
+}
+export interface SkillExecutionResult {
+    requestId: string;
+    skillName: string;
+    status: string;
+    output: unknown;
+    error?: unknown;
+    messageId: string;
+    deliveryId: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/openclaw.plugin.json

@@ -0,0 +1,34 @@
+{
+  "id": "statocyst-openclaw",
+  "name": "Statocyst Realtime",
+  "description": "Realtime Statocyst messaging and skill request/result tools for OpenClaw.",
+  "version": "0.1.0",
+  "contracts": {
+    "tools": ["statocyst_skill_request", "statocyst_session_status"]
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["baseUrl", "token"],
+    "properties": {
+      "baseUrl": {
+        "type": "string",
+        "description": "Statocyst API base URL, for example https://hub.example.com/v1"
+      },
+      "token": {
+        "type": "string",
+        "description": "Statocyst agent bearer token"
+      },
+      "sessionKey": {
+        "type": "string",
+        "description": "Dedicated realtime session key",
+        "default": "main"
+      },
+      "timeoutMs": {
+        "type": "number",
+        "description": "Request timeout in milliseconds",
+        "default": 20000
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@moltenbot/openclaw-plugin-statocyst",
+  "version": "0.1.0",
+  "description": "OpenClaw plugin for realtime Statocyst skill request/result messaging.",
+  "type": "module",
+  "homepage": "https://molten.bot",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Molten-Bot/statocyst",
+    "directory": "statocyst-openclaw-plugin"
+  },
+  "bugs": {
+    "url": "https://github.com/Molten-Bot/statocyst/issues"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "install": {
+      "npmSpec": "@moltenbot/openclaw-plugin-statocyst",
+      "defaultChoice": "npm:@moltenbot/openclaw-plugin-statocyst"
+    }
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "openclaw.plugin.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:e2e:container": "node scripts/e2e-container.mjs",
+  "prepublishOnly": "npm run build && npm run test:coverage"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "openclaw",
+    "statocyst",
+    "plugin",
+    "realtime",
+    "molten-ai"
+  ],
+  "author": "Molten AI (https://molten.bot)",
+  "license": "MIT",
+  "dependencies": {
+    "ws": "^8.18.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "@types/ws": "^8.18.1",
+    "@vitest/coverage-v8": "^3.2.4",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  }
+}