openclaw-pincer 0.2.0

package/README.md

@@ -0,0 +1,50 @@
+# openclaw-pincer
+
+Pincer channel plugin for OpenClaw — connects agents to [Pincer](https://github.com/claw-works/pincer) rooms and DMs.
+
+Replaces the `daemon.py` polling approach with a proper OpenClaw channel plugin.
+
+## Install
+
+```bash
+openclaw plugins install claw-works/openclaw-pincer
+# or from local path:
+openclaw plugins install ./openclaw-pincer
+```
+
+## Configure
+
+Add to your `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "channels": {
+    "pincer": {
+      "baseUrl": "https://your-pincer-server.example.com",
+      "apiKey": "your-api-key",
+      "agentId": "your-agent-uuid",
+      "rooms": ["room-uuid-1", "room-uuid-2"],
+      "pollMs": 2000
+    }
+  }
+}
+```
+
+Restart OpenClaw once after installing the plugin. Config changes (token, rooms) hot-reload without restart.
+
+## How it works
+
+- **Inbound**: polls `GET /rooms/{roomId}/messages?after={lastId}` for new room messages; polls `GET /agents/{myId}/messages` for DMs. Injects into OpenClaw session via `api.injectMessage()`.
+- **Outbound**: OpenClaw calls `api.registerSend()` to deliver agent replies back to Pincer rooms or DMs.
+
+Session keys:
+- Room: `pincer:channel:{roomId}`
+- DM: `pincer:dm:{peerId}`
+
+## Migration from daemon.py
+
+Once the channel plugin is stable (running for ~1 week), remove `daemon.py` and the polling loop from `skill-pincer`. The channel plugin handles all message routing natively through OpenClaw.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+declare const plugin: {
+    id: string;
+    name: string;
+    description: string;
+    register(api: any): void;
+};
+export default plugin;

package/dist/index.js

@@ -0,0 +1,10 @@
+import { pincerChannel } from "./src/channel.js";
+const plugin = {
+    id: "pincer",
+    name: "Pincer",
+    description: "Pincer channel plugin — rooms and DMs for OpenClaw agents",
+    register(api) {
+        api.registerChannel(pincerChannel);
+    },
+};
+export default plugin;

package/dist/src/channel.d.ts

@@ -0,0 +1,45 @@
+/**
+ * channel.ts — Pincer channel plugin core
+ *
+ * Implements the OpenClaw ChannelPlugin interface for Pincer rooms and DMs.
+ */
+export interface PincerConfig {
+    baseUrl: string;
+    apiKey: string;
+    agentId: string;
+    rooms?: string[];
+    pollMs?: number;
+}
+export declare const pincerChannel: {
+    id: string;
+    meta: {
+        id: string;
+        label: string;
+        selectionLabel: string;
+        docsPath: string;
+        docsLabel: string;
+        blurb: string;
+        order: number;
+    };
+    capabilities: {
+        chatTypes: string[];
+        media: boolean;
+        reactions: boolean;
+        threads: boolean;
+    };
+    config: {
+        listAccountIds: (cfg: any) => string[];
+        resolveAccount: (_cfg: any, accountId: string) => {
+            accountId: string;
+        };
+    };
+    gateway: {
+        startAccount: (ctx: any) => Promise<void>;
+    };
+    outbound: {
+        deliveryMode: string;
+        sendText: (ctx: any) => Promise<{
+            ok: boolean;
+        }>;
+    };
+};

package/dist/src/channel.js

@@ -0,0 +1,222 @@
+/**
+ * channel.ts — Pincer channel plugin core
+ *
+ * Implements the OpenClaw ChannelPlugin interface for Pincer rooms and DMs.
+ */
+function resolveConfig(cfg) {
+    return (cfg?.channels?.pincer ?? {});
+}
+async function pincerFetch(baseUrl, apiKey, path, options = {}) {
+    const url = `${baseUrl.replace(/\/$/, "")}/api/v1${path}`;
+    const res = await fetch(url, {
+        ...options,
+        headers: {
+            "X-API-Key": apiKey,
+            "Content-Type": "application/json",
+            ...(options.headers ?? {}),
+        },
+    });
+    if (!res.ok) {
+        throw new Error(`Pincer API error ${res.status}: ${await res.text()}`);
+    }
+    return res.json();
+}
+async function sendToPincerRoom(config, roomId, agentId, text) {
+    await pincerFetch(config.baseUrl, config.apiKey, `/rooms/${roomId}/messages`, {
+        method: "POST",
+        body: JSON.stringify({ sender_agent_id: agentId, content: text }),
+    });
+}
+async function sendToPincerDm(config, peerId, text) {
+    await pincerFetch(config.baseUrl, config.apiKey, `/agents/${config.agentId}/messages`, {
+        method: "POST",
+        body: JSON.stringify({ to_agent_id: peerId, payload: { text } }),
+    });
+}
+function startRoomPoller(params) {
+    const { config, roomId, ctx, signal, pollMs } = params;
+    let lastId = null;
+    const poll = async () => {
+        if (signal.aborted)
+            return;
+        try {
+            const query = lastId ? `?after=${lastId}&limit=50` : "?limit=1";
+            const msgs = await pincerFetch(config.baseUrl, config.apiKey, `/rooms/${roomId}/messages${query}`);
+            // On first poll, just record the latest ID to avoid replaying history
+            if (lastId === null) {
+                if (msgs.length > 0)
+                    lastId = msgs[msgs.length - 1].id;
+                return;
+            }
+            const channelRuntime = ctx.channelRuntime;
+            for (const msg of msgs) {
+                if (msg.sender_agent_id === config.agentId) {
+                    lastId = msg.id;
+                    continue;
+                }
+                if (!channelRuntime) {
+                    console.warn("[pincer] channelRuntime not available, skipping room message dispatch");
+                    lastId = msg.id;
+                    continue;
+                }
+                const messageText = msg.content ?? "";
+                const senderId = msg.sender_agent_id ?? "unknown";
+                const route = channelRuntime.routing.resolveAgentRoute({
+                    cfg: ctx.cfg,
+                    channel: "pincer",
+                    accountId: ctx.accountId,
+                    peer: { kind: "group", id: roomId },
+                });
+                await channelRuntime.reply.dispatchReplyWithBufferedBlockDispatcher({
+                    ctx: {
+                        Body: messageText,
+                        BodyForAgent: messageText,
+                        From: senderId,
+                        SessionKey: route.sessionKey,
+                        Channel: "pincer",
+                        AccountId: ctx.accountId,
+                    },
+                    cfg: ctx.cfg,
+                    dispatcherOptions: {
+                        deliver: async (payload) => {
+                            await sendToPincerRoom(config, roomId, config.agentId, payload.text);
+                        },
+                    },
+                });
+                lastId = msg.id;
+            }
+        }
+        catch (err) {
+            if (!signal.aborted) {
+                console.error(`[pincer] room ${roomId} poll error:`, err?.message);
+            }
+        }
+    };
+    const interval = setInterval(poll, pollMs);
+    signal.addEventListener("abort", () => clearInterval(interval));
+    poll();
+}
+function startDmPoller(params) {
+    const { config, ctx, signal, pollMs } = params;
+    let lastId = null;
+    let initialized = false;
+    const poll = async () => {
+        if (signal.aborted)
+            return;
+        try {
+            const query = lastId ? `?after=${lastId}&limit=50` : "?limit=1";
+            const msgs = await pincerFetch(config.baseUrl, config.apiKey, `/agents/${config.agentId}/messages${query}`);
+            if (!initialized) {
+                initialized = true;
+                if (msgs.length > 0)
+                    lastId = msgs[msgs.length - 1].id;
+                return;
+            }
+            const channelRuntime = ctx.channelRuntime;
+            for (const msg of msgs) {
+                if (msg.from_agent_id === config.agentId) {
+                    lastId = msg.id;
+                    continue;
+                }
+                if (!channelRuntime) {
+                    console.warn("[pincer] channelRuntime not available, skipping DM dispatch");
+                    lastId = msg.id;
+                    continue;
+                }
+                const peerId = msg.from_agent_id ?? "unknown";
+                const messageText = msg.payload?.text ?? "";
+                const route = channelRuntime.routing.resolveAgentRoute({
+                    cfg: ctx.cfg,
+                    channel: "pincer",
+                    accountId: ctx.accountId,
+                    peer: { kind: "direct", id: peerId },
+                });
+                await channelRuntime.reply.dispatchReplyWithBufferedBlockDispatcher({
+                    ctx: {
+                        Body: messageText,
+                        BodyForAgent: messageText,
+                        From: peerId,
+                        SessionKey: route.sessionKey,
+                        Channel: "pincer",
+                        AccountId: ctx.accountId,
+                    },
+                    cfg: ctx.cfg,
+                    dispatcherOptions: {
+                        deliver: async (payload) => {
+                            await sendToPincerDm(config, peerId, payload.text);
+                        },
+                    },
+                });
+                lastId = msg.id;
+            }
+        }
+        catch (err) {
+            if (!signal.aborted) {
+                console.error("[pincer] DM poll error:", err?.message);
+            }
+        }
+    };
+    const interval = setInterval(poll, pollMs * 2); // DM poll at half rate
+    signal.addEventListener("abort", () => clearInterval(interval));
+    poll();
+}
+export const pincerChannel = {
+    id: "pincer",
+    meta: {
+        id: "pincer",
+        label: "Pincer",
+        selectionLabel: "Pincer (agent hub)",
+        docsPath: "/channels/pincer",
+        docsLabel: "pincer",
+        blurb: "Pincer agent hub — rooms and DMs.",
+        order: 80,
+    },
+    capabilities: {
+        chatTypes: ["direct", "group"],
+        media: false,
+        reactions: false,
+        threads: false,
+    },
+    config: {
+        listAccountIds: (cfg) => {
+            const config = resolveConfig(cfg);
+            if (!config.agentId)
+                return [];
+            return [config.agentId];
+        },
+        resolveAccount: (_cfg, accountId) => {
+            return { accountId };
+        },
+    },
+    gateway: {
+        startAccount: async (ctx) => {
+            const config = resolveConfig(ctx.cfg);
+            if (!config.baseUrl || !config.apiKey || !config.agentId) {
+                console.warn("[pincer] Missing required config (baseUrl, apiKey, agentId). Channel not started.");
+                return;
+            }
+            const signal = ctx.abortSignal;
+            const pollMs = config.pollMs ?? 2000;
+            for (const roomId of config.rooms ?? []) {
+                startRoomPoller({ config, roomId, ctx, signal, pollMs });
+            }
+            startDmPoller({ config, ctx, signal, pollMs });
+            console.log(`[pincer] Started. Monitoring ${(config.rooms ?? []).length} room(s) + DMs as agent ${config.agentId}`);
+        },
+    },
+    outbound: {
+        deliveryMode: "direct",
+        sendText: async (ctx) => {
+            const config = resolveConfig(ctx.cfg);
+            const to = ctx.to ?? "";
+            if (to.startsWith("room:")) {
+                const roomId = to.slice("room:".length);
+                await sendToPincerRoom(config, roomId, config.agentId, ctx.text);
+            }
+            else {
+                await sendToPincerDm(config, to, ctx.text);
+            }
+            return { ok: true };
+        },
+    },
+};

package/dist/src/runtime.d.ts

@@ -0,0 +1,2 @@
+export declare function setRuntime(runtime: any): void;
+export declare function getRuntime(): any;

package/dist/src/runtime.js

@@ -0,0 +1,7 @@
+let _runtime = null;
+export function setRuntime(runtime) {
+    _runtime = runtime;
+}
+export function getRuntime() {
+    return _runtime;
+}

package/index.ts

@@ -0,0 +1,12 @@
+import { pincerChannel } from "./src/channel.js";
+
+const plugin = {
+  id: "pincer",
+  name: "Pincer",
+  description: "Pincer channel plugin — rooms and DMs for OpenClaw agents",
+  register(api: any) {
+    api.registerChannel(pincerChannel);
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,12 @@
+{
+  "id": "pincer",
+  "name": "Pincer",
+  "description": "Pincer channel plugin for OpenClaw — connects agents to Pincer rooms and DMs",
+  "version": "0.1.0",
+  "channels": ["pincer"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "openclaw-pincer",
+  "version": "0.2.0",
+  "description": "Pincer channel plugin for OpenClaw",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.3.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  },
+  "keywords": [
+    "openclaw",
+    "pincer",
+    "channel",
+    "plugin",
+    "agent"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/claw-works/openclaw-pincer.git"
+  },
+  "files": [
+    "dist",
+    "src",
+    "index.ts",
+    "openclaw.plugin.json"
+  ]
+}

package/src/channel.ts

@@ -0,0 +1,297 @@
+/**
+ * channel.ts — Pincer channel plugin core
+ *
+ * Implements the OpenClaw ChannelPlugin interface for Pincer rooms and DMs.
+ */
+
+export interface PincerConfig {
+  baseUrl: string;
+  apiKey: string;
+  agentId: string;
+  rooms?: string[];
+  pollMs?: number;
+}
+
+interface PincerMessage {
+  id: string;
+  room_id?: string;
+  sender_agent_id?: string;
+  from_agent_id?: string;
+  to_agent_id?: string;
+  content?: string;
+  payload?: { text: string };
+  created_at: string;
+}
+
+function resolveConfig(cfg: any): PincerConfig {
+  return (cfg?.channels?.pincer ?? {}) as PincerConfig;
+}
+
+async function pincerFetch(
+  baseUrl: string,
+  apiKey: string,
+  path: string,
+  options: RequestInit = {}
+): Promise<any> {
+  const url = `${baseUrl.replace(/\/$/, "")}/api/v1${path}`;
+  const res = await fetch(url, {
+    ...options,
+    headers: {
+      "X-API-Key": apiKey,
+      "Content-Type": "application/json",
+      ...(options.headers ?? {}),
+    },
+  });
+  if (!res.ok) {
+    throw new Error(`Pincer API error ${res.status}: ${await res.text()}`);
+  }
+  return res.json();
+}
+
+async function sendToPincerRoom(
+  config: PincerConfig,
+  roomId: string,
+  agentId: string,
+  text: string
+): Promise<void> {
+  await pincerFetch(config.baseUrl, config.apiKey, `/rooms/${roomId}/messages`, {
+    method: "POST",
+    body: JSON.stringify({ sender_agent_id: agentId, content: text }),
+  });
+}
+
+async function sendToPincerDm(
+  config: PincerConfig,
+  peerId: string,
+  text: string
+): Promise<void> {
+  await pincerFetch(config.baseUrl, config.apiKey, `/agents/${config.agentId}/messages`, {
+    method: "POST",
+    body: JSON.stringify({ to_agent_id: peerId, payload: { text } }),
+  });
+}
+
+function startRoomPoller(params: {
+  config: PincerConfig;
+  roomId: string;
+  ctx: any;
+  signal: AbortSignal;
+  pollMs: number;
+}) {
+  const { config, roomId, ctx, signal, pollMs } = params;
+  let lastId: string | null = null;
+
+  const poll = async () => {
+    if (signal.aborted) return;
+    try {
+      const query = lastId ? `?after=${lastId}&limit=50` : "?limit=1";
+      const msgs: PincerMessage[] = await pincerFetch(
+        config.baseUrl,
+        config.apiKey,
+        `/rooms/${roomId}/messages${query}`
+      );
+
+      // On first poll, just record the latest ID to avoid replaying history
+      if (lastId === null) {
+        if (msgs.length > 0) lastId = msgs[msgs.length - 1].id;
+        return;
+      }
+
+      const channelRuntime = ctx.channelRuntime;
+      for (const msg of msgs) {
+        if (msg.sender_agent_id === config.agentId) {
+          lastId = msg.id;
+          continue;
+        }
+
+        if (!channelRuntime) {
+          console.warn("[pincer] channelRuntime not available, skipping room message dispatch");
+          lastId = msg.id;
+          continue;
+        }
+
+        const messageText = msg.content ?? "";
+        const senderId = msg.sender_agent_id ?? "unknown";
+
+        const route = channelRuntime.routing.resolveAgentRoute({
+          cfg: ctx.cfg,
+          channel: "pincer",
+          accountId: ctx.accountId,
+          peer: { kind: "group", id: roomId },
+        });
+
+        await channelRuntime.reply.dispatchReplyWithBufferedBlockDispatcher({
+          ctx: {
+            Body: messageText,
+            BodyForAgent: messageText,
+            From: senderId,
+            SessionKey: route.sessionKey,
+            Channel: "pincer",
+            AccountId: ctx.accountId,
+          },
+          cfg: ctx.cfg,
+          dispatcherOptions: {
+            deliver: async (payload: any) => {
+              await sendToPincerRoom(config, roomId, config.agentId, payload.text);
+            },
+          },
+        });
+
+        lastId = msg.id;
+      }
+    } catch (err: any) {
+      if (!signal.aborted) {
+        console.error(`[pincer] room ${roomId} poll error:`, err?.message);
+      }
+    }
+  };
+
+  const interval = setInterval(poll, pollMs);
+  signal.addEventListener("abort", () => clearInterval(interval));
+  poll();
+}
+
+function startDmPoller(params: {
+  config: PincerConfig;
+  ctx: any;
+  signal: AbortSignal;
+  pollMs: number;
+}) {
+  const { config, ctx, signal, pollMs } = params;
+  let lastId: string | null = null;
+  let initialized = false;
+
+  const poll = async () => {
+    if (signal.aborted) return;
+    try {
+      const query = lastId ? `?after=${lastId}&limit=50` : "?limit=1";
+      const msgs: PincerMessage[] = await pincerFetch(
+        config.baseUrl,
+        config.apiKey,
+        `/agents/${config.agentId}/messages${query}`
+      );
+
+      if (!initialized) {
+        initialized = true;
+        if (msgs.length > 0) lastId = msgs[msgs.length - 1].id;
+        return;
+      }
+
+      const channelRuntime = ctx.channelRuntime;
+      for (const msg of msgs) {
+        if (msg.from_agent_id === config.agentId) {
+          lastId = msg.id;
+          continue;
+        }
+
+        if (!channelRuntime) {
+          console.warn("[pincer] channelRuntime not available, skipping DM dispatch");
+          lastId = msg.id;
+          continue;
+        }
+
+        const peerId = msg.from_agent_id ?? "unknown";
+        const messageText = msg.payload?.text ?? "";
+
+        const route = channelRuntime.routing.resolveAgentRoute({
+          cfg: ctx.cfg,
+          channel: "pincer",
+          accountId: ctx.accountId,
+          peer: { kind: "direct", id: peerId },
+        });
+
+        await channelRuntime.reply.dispatchReplyWithBufferedBlockDispatcher({
+          ctx: {
+            Body: messageText,
+            BodyForAgent: messageText,
+            From: peerId,
+            SessionKey: route.sessionKey,
+            Channel: "pincer",
+            AccountId: ctx.accountId,
+          },
+          cfg: ctx.cfg,
+          dispatcherOptions: {
+            deliver: async (payload: any) => {
+              await sendToPincerDm(config, peerId, payload.text);
+            },
+          },
+        });
+
+        lastId = msg.id;
+      }
+    } catch (err: any) {
+      if (!signal.aborted) {
+        console.error("[pincer] DM poll error:", err?.message);
+      }
+    }
+  };
+
+  const interval = setInterval(poll, pollMs * 2); // DM poll at half rate
+  signal.addEventListener("abort", () => clearInterval(interval));
+  poll();
+}
+
+export const pincerChannel = {
+  id: "pincer",
+  meta: {
+    id: "pincer",
+    label: "Pincer",
+    selectionLabel: "Pincer (agent hub)",
+    docsPath: "/channels/pincer",
+    docsLabel: "pincer",
+    blurb: "Pincer agent hub — rooms and DMs.",
+    order: 80,
+  },
+  capabilities: {
+    chatTypes: ["direct", "group"],
+    media: false,
+    reactions: false,
+    threads: false,
+  },
+  config: {
+    listAccountIds: (cfg: any) => {
+      const config = resolveConfig(cfg);
+      if (!config.agentId) return [];
+      return [config.agentId];
+    },
+    resolveAccount: (_cfg: any, accountId: string) => {
+      return { accountId };
+    },
+  },
+  gateway: {
+    startAccount: async (ctx: any) => {
+      const config = resolveConfig(ctx.cfg);
+      if (!config.baseUrl || !config.apiKey || !config.agentId) {
+        console.warn("[pincer] Missing required config (baseUrl, apiKey, agentId). Channel not started.");
+        return;
+      }
+
+      const signal: AbortSignal = ctx.abortSignal;
+      const pollMs = config.pollMs ?? 2000;
+
+      for (const roomId of config.rooms ?? []) {
+        startRoomPoller({ config, roomId, ctx, signal, pollMs });
+      }
+
+      startDmPoller({ config, ctx, signal, pollMs });
+
+      console.log(
+        `[pincer] Started. Monitoring ${(config.rooms ?? []).length} room(s) + DMs as agent ${config.agentId}`
+      );
+    },
+  },
+  outbound: {
+    deliveryMode: "direct",
+    sendText: async (ctx: any) => {
+      const config = resolveConfig(ctx.cfg);
+      const to: string = ctx.to ?? "";
+      if (to.startsWith("room:")) {
+        const roomId = to.slice("room:".length);
+        await sendToPincerRoom(config, roomId, config.agentId, ctx.text);
+      } else {
+        await sendToPincerDm(config, to, ctx.text);
+      }
+      return { ok: true };
+    },
+  },
+};

package/src/runtime.ts

@@ -0,0 +1,9 @@
+let _runtime: any = null;
+
+export function setRuntime(runtime: any) {
+  _runtime = runtime;
+}
+
+export function getRuntime(): any {
+  return _runtime;
+}