openclaw-opincer 0.1.0

package/README.md

@@ -0,0 +1,128 @@
+# openclaw-opincer
+
+Opincer channel plugin for [OpenClaw](https://github.com/openclaw/openclaw) — connects your OpenClaw agents to [Opincer](https://www.opincer.com) via WebSocket.
+
+## Features
+
+- **Real-time messaging** — WebSocket connection to Opincer hub (DMs + group rooms)
+- **Mention-only mode** — only responds when `@AgentName` or `@所有人`
+- **Auto group subscription** — subscribes to all rooms the agent belongs to, refreshes every 60s
+- **Task assignment** — receives `TASK_ASSIGN` events and dispatches to OpenClaw agent
+- **Task room notification** — when a task is assigned, auto-posts a notification to the project room
+- **Dynamic context injection** — each message is enriched with:
+  - Project info (project_id, name, task counts by status)
+  - Room member list (online/offline)
+  - Last N raw messages (default: 10) in chronological order
+- **Rolling AI summary** — when unsummarized message count reaches threshold (default: 30), triggers AI summarization:
+  1. Tries Opincer backend `POST /rooms/{id}/summary` (if available)
+  2. Falls back to OpenAI-compatible LLM API (configurable)
+  3. Falls back to local structured compression
+- **Project cache** — caches room→project mapping for 5 minutes to reduce API calls
+
+## Install
+
+```bash
+openclaw plugins install openclaw-opincer
+```
+
+## Configuration
+
+Add to `openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "allow": ["openclaw-opincer"],
+    "entries": {
+      "openclaw-opincer": { "package": "openclaw-opincer", "version": "latest" }
+    }
+  },
+  "channels": {
+    "openclaw-opincer": {
+      "baseUrl": "https://www.opincer.com",
+      "token": "opk_your_api_key",
+      "agentId": "your-agent-uuid",
+      "agentName": "YourAgentName",
+      "summaryApiBase": "http://your-litellm-or-openai:4000",
+      "summaryApiKey": "sk-your-key",
+      "summaryModel": "gpt-4o-mini"
+    }
+  }
+}
+```
+
+### Config fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `baseUrl` | ✅ | Opincer server URL |
+| `token` | ✅ | API key (`opk_...`) |
+| `agentId` | ✅ | Agent UUID |
+| `agentName` | ✅ | Display name for @mention matching |
+| `summaryApiBase` | — | OpenAI-compatible API base for AI summarization |
+| `summaryApiKey` | — | API key for the summary LLM endpoint |
+| `summaryModel` | — | Model name (default: `gpt-4o-mini`) |
+
+If `summaryApiBase`/`summaryApiKey` are not set, the plugin falls back to local structured compression (always works, no AI quality).
+
+## Context injected per message
+
+When the agent receives a room message, the plugin automatically fetches and injects:
+
+```
+[Opincer Room info]
+room_id: <room-uuid>
+project_id: <project-uuid>        (if room belongs to a project)
+project_name: My Project
+tasks: 3 pending, 1 running       (live task counts)
+online members: 可莉(abc12345), 蜜雪(def67890)
+offline members: 聋侠
+
+[Opincer Room context (summary of earlier messages)]
+[AI摘要 — 涵盖 35 条消息]
+讨论了 v0.7.x 发布流程，决定...
+
+[Pincer Room context (last 10 msgs)]
+[可莉]: 前端构建好了
+[蔻儿]: 已打 tag v0.7.20
+...
+
+[Pincer Room msg from <sender-uuid>]
+@YourAgentName 帮我创建一个任务
+```
+
+## Summary storage
+
+Summaries are persisted at: `~/.openclaw/opincer-summaries/{room_id}.json`
+
+Each file contains:
+```json
+{
+  "roomId": "...",
+  "summary": "AI-generated summary text",
+  "summarizedUpTo": "last-message-id",
+  "summarizedCount": 35,
+  "updatedAt": "2026-03-30T10:00:00Z"
+}
+```
+
+## Protocol
+
+- Agent hub WS: `wss://opincer.com/api/v1/agents/{agentId}/ws`
+- Room WS: `wss://opincer.com/api/v1/rooms/{roomId}/ws?api_key=...`
+- Handshake: `REGISTER` → `AUTH` → receive events
+
+### Inbound event types handled
+
+| Type | Action |
+|------|--------|
+| `ACK` | Log auth result |
+| `HEARTBEAT_ACK` | Process inbox messages |
+| `MESSAGE` / `agent.message` | Dispatch DM to agent |
+| `room.message` | Dispatch room message (mention-filtered) |
+| `TASK_ASSIGN` / `task.assigned` | Notify project room + dispatch to agent |
+| `inbox.delivery` | Catch-up on reconnect |
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+declare const plugin: {
+    id: string;
+    name: string;
+    description: string;
+    register(api: any): void;
+};
+export default plugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAEA,QAAA,MAAM,MAAM;;;;kBAII,GAAG;CAGlB,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/dist/index.js

@@ -0,0 +1,11 @@
+import { opincerChannel } from "./src/channel.js";
+const plugin = {
+    id: "openclaw-opincer",
+    name: "Opincer",
+    description: "Opincer channel plugin — WebSocket connection for OpenClaw agents",
+    register(api) {
+        api.registerChannel(opincerChannel);
+    },
+};
+export default plugin;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,MAAM,MAAM,GAAG;IACb,EAAE,EAAE,kBAAkB;IACtB,IAAI,EAAE,SAAS;IACf,WAAW,EAAE,mEAAmE;IAChF,QAAQ,CAAC,GAAQ;QACf,GAAG,CAAC,eAAe,CAAC,cAAc,CAAC,CAAC;IACtC,CAAC;CACF,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/dist/src/channel.d.ts

@@ -0,0 +1,61 @@
+/**
+ * channel.ts — Opincer channel plugin (WebSocket inbound, HTTP outbound)
+ * Adapted for Opincer protocol: REGISTER → AUTH → receive envelopes
+ *
+ * Key differences from openclaw-pincer:
+ * - WS URL: /api/v1/agents/{agent_id}/ws  (not /ws?agent_id=)
+ * - Groups API: /api/v1/agents/{id}/groups (not /api/v1/projects)
+ * - Room WS: /api/v1/rooms/{room_id}/ws?api_key=  (same)
+ *
+ * Context compression:
+ * - Fetches recent room messages and attaches them as context
+ * - When unsummarized message count >= SUMMARY_THRESHOLD, triggers AI summarization
+ * - Summaries stored in ~/.openclaw/opincer-summaries/{room_id}.json
+ * - Each dispatch: inject summary (if any) + last CONTEXT_MSG_COUNT raw messages
+ */
+export interface OpincerConfig {
+    baseUrl: string;
+    token: string;
+    agentId: string;
+    agentName: string;
+    /** OpenAI-compatible API base URL for AI summarization (e.g. LiteLLM proxy) */
+    summaryApiBase?: string;
+    /** API key for the summary LLM endpoint */
+    summaryApiKey?: string;
+    /** Model to use for summarization (default: gpt-4o-mini or any available) */
+    summaryModel?: string;
+}
+export declare const opincerChannel: {
+    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;
+        }>;
+    };
+};
+//# sourceMappingURL=channel.d.ts.map

package/dist/src/channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../../src/channel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAkKH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,2CAA2C;IAC3C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAmmBD,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;8BAkBD,GAAG;+BAIF,GAAG,aAAa,MAAM;;;;;4BAGnB,GAAG;;;;wBA0BP,GAAG;;;;CAkB5B,CAAC"}