@ascegu/teamily 1.0.15 → 1.0.17

package/README.md

@@ -1,41 +1,54 @@
 # Teamily Channel Plugin for OpenClaw
 
-This plugin integrates Teamily Server (based on OpenIM) with OpenClaw, allowing you to use OpenClaw as a bot in your self-hosted team messaging platform.
+Integrates [Teamily](https://teamily.ai/) (based on OpenIM) with OpenClaw as a self-hosted team messaging channel.
 
-## Teamily Server
+## Installation
 
-Teamily is a team instant messaging server based on OpenIM open-source platform. For more information about OpenIM, visit: https://github.com/openimsdk/open-im-server
+```bash
+openclaw plugins install @ascegu/teamily
+```
 
-## Installation
+Or update an existing install:
 
 ```bash
-openclaw plugins install @openclaw/teamily
+openclaw plugins update teamily
 ```
 
-## Configuration
+> **Note:** The plugin update command uses the plugin ID `teamily`, not the npm package name.
 
-### Server Configuration
+## Configuration
 
-Configure your Teamily server connection:
+### Interactive Setup
 
 ```bash
 openclaw channel configure teamily
 ```
 
-Required server settings:
+### Server Settings
+
+| Field         | Description              | Default                   |
+|---------------|--------------------------|---------------------------|
+| `platformUrl` | Teamily platform URL     | `http://localhost:10002`  |
+| `apiURL`      | Teamily REST API URL     | `http://localhost:10002`  |
+| `wsURL`       | Teamily WebSocket URL    | `ws://localhost:10001`    |
+
+### Bot Account Settings
 
-- `platformUrl`: Teamily platform URL (default: `http://localhost:10002`)
-- `apiURL`: Teamily REST API URL (default: `http://localhost:10002`)
-- `wsURL`: Teamily WebSocket URL (default: `ws://localhost:10001`)
+| Field      | Required | Description                     |
+|------------|----------|---------------------------------|
+| `userID`   | Yes      | User ID for the bot account     |
+| `token`    | Yes      | User token for authentication   |
+| `nickname` | No       | Display nickname                |
+| `faceURL`  | No       | Avatar URL                      |
 
-### Bot Account Configuration
+### DM Security
 
-Configure a bot user account:
+Per-account or channel-level DM security can be configured:
 
-- `userID`: User ID for the bot account
-- `token`: User token for authentication
-- `nickname`: (optional) Display nickname
-- `faceURL`: (optional) Avatar URL
+| Field              | Description                                          |
+|--------------------|------------------------------------------------------|
+| `dm.policy`        | DM security policy (`pairing`, `allowlist`, `open`)  |
+| `dm.allowFrom`     | List of allowed sender IDs                           |
 
 ### Example Configuration
 
@@ -44,27 +57,29 @@ channels:
   teamily:
     enabled: true
     server:
-      platformUrl: http://localhost:10002
-      apiURL: http://localhost:10002
-      wsURL: ws://localhost:10001
+      platformUrl: http://your-server:10002
+      apiURL: http://your-server:10002
+      wsURL: ws://your-server:10001
     accounts:
       default:
-        userID: "your-bot-user-id"
-        token: "your-bot-token"
+        userID: "bot-user-id"
+        token: "bot-token"
         nickname: "OpenClaw Bot"
+        dm:
+          policy: open
 ```
 
+Multiple accounts are supported under the `accounts` key.
+
 ## Usage
 
-### Send a Message to a User
+### Send Messages
 
 ```bash
+# Send to a user
 openclaw message send teamily:user:userID "Hello!"
-```
 
-### Send a Message to a Group
-
-```bash
+# Send to a group
 openclaw message send teamily:group:groupID "Hello group!"
 ```
 
@@ -74,34 +89,65 @@ openclaw message send teamily:group:groupID "Hello group!"
 openclaw message send teamily:user:userID --media /path/to/image.jpg
 ```
 
-## Setting Up Teamily
+Supported media types are auto-detected by file extension:
 
-### 1. Start Teamily Server
+| Extension                    | Type  |
+|------------------------------|-------|
+| `.jpg`, `.png`, `.gif`, etc. | Image |
+| `.mp4`, `.mov`, `.webm`     | Video |
+| `.mp3`, `.m4a`, `.wav`      | Audio |
+| `.pdf`, `.doc`, `.docx`, `.zip` | File |
 
-Follow the [OpenIM Quick Start](https://docs.openim.io/guides/gettingStarted/introduction) guide to deploy the server (Teamily is based on OpenIM).
+## Group Chat Behavior
 
-### 2. Create a Bot User
+- The bot only **replies** to messages where it is **@-mentioned** (`@BotName`).
+- Non-@-mention group messages are **buffered in memory** (up to 50 per group) and injected as conversation context when an @-mention triggers a reply. The buffer is cleared after each dispatch so context doesn't repeat.
+- In direct messages, the bot always replies.
+- Both regular groups (`sessionType=3`) and super groups (`sessionType=2`) are supported.
 
-Use the Teamily management API to create a bot user account and obtain its user ID and token.
+## Capabilities
 
-### 3. Configure OpenClaw
+| Feature                   | Supported |
+|---------------------------|-----------|
+| Direct messaging          | Yes       |
+| Group messaging           | Yes       |
+| Text messages             | Yes       |
+| Media (image/video/audio/file) | Yes |
+| @-mention gating (groups) | Yes       |
+| Group history context (50 msg buffer) | Yes |
+| WebSocket real-time monitoring | Yes  |
+| Automatic reconnection    | Yes       |
+| Connection health probes  | Yes       |
+| Reactions                 | No        |
+| Threads                   | No        |
+| Polls                     | No        |
 
-Configure the Teamily channel with your server details and bot credentials.
+## Setting Up Teamily Server
 
-## Features
+1. **Deploy OpenIM server** -- follow the [OpenIM Quick Start](https://docs.openim.io/guides/gettingStarted/introduction) guide.
+2. **Create a bot user** -- use the Teamily management API to create a bot account and obtain its `userID` and `token`.
+3. **Configure OpenClaw** -- run `openclaw channel configure teamily` and provide the server URLs and bot credentials.
 
-- ✅ Direct messaging
-- ✅ Group messaging
-- ✅ Text messages
-- ✅ Media messages (images, videos, audio, files)
-- ✅ WebSocket real-time message monitoring
-- ✅ Automatic reconnection
-- ✅ Connection health checks
+## Architecture
+
+```
+index.ts              Plugin entry point (registers channel with OpenClaw)
+src/
+  channel.ts          Channel plugin definition (gateway, outbound, config, security)
+  monitor.ts          WebSocket monitor using @openim/client-sdk (inbound + send)
+  types.ts            Shared types and constants (session types, content types, message shapes)
+  config-schema.ts    Zod config schema (server, accounts, DM security)
+  accounts.ts         Account resolution and listing
+  normalize.ts        Target ID normalization (user:ID, group:ID)
+  probe.ts            Health check via REST API
+  runtime.ts          Plugin runtime store
+  send.ts             REST API message/media send (fallback path)
+```
 
-## Supported API Versions
+## Compatibility
 
-This plugin is designed to work with OpenIM API v2/v3 (which Teamily is based on). Please refer to the official OpenIM documentation for API details: https://docs.openim.io
+Designed for OpenIM API v2/v3. Requires `@openim/client-sdk` ^3.8.3.
 
 ## License
 
-This plugin is part of OpenClaw and follows the same license terms.
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ascegu/teamily",
-  "version": "1.0.15",
+  "version": "1.0.17",
   "description": "OpenClaw Teamily channel plugin - Team instant messaging server integration",
   "keywords": [
     "channel",

package/src/channel.ts

@@ -1,14 +1,19 @@
 import {
   applyAccountNameToChannelSection,
   buildChannelConfigSchema,
+  buildPendingHistoryContextFromMap,
+  clearHistoryEntriesIfEnabled,
   DEFAULT_ACCOUNT_ID,
+  DEFAULT_GROUP_HISTORY_LIMIT,
   deleteAccountFromConfigSection,
   normalizeAccountId,
   PAIRING_APPROVED_MESSAGE,
+  recordPendingHistoryEntryIfEnabled,
   setAccountEnabledInConfigSection,
   type ChannelPlugin,
   type ChannelOutboundContext,
   type ChannelStatusIssue,
+  type HistoryEntry,
 } from "openclaw/plugin-sdk";
 import {
   buildAccountScopedDmSecurityPolicy,
@@ -238,24 +243,43 @@ export const teamilyPlugin: ChannelPlugin<ResolvedTeamilyAccount> = {
       log?.info?.(`Starting Teamily channel (account: ${accountId})`);
 
       const MEDIA_MAX_BYTES = 5 * 1024 * 1024; // 5 MB
+      const historyLimit = DEFAULT_GROUP_HISTORY_LIMIT; // 50 messages per group
+      const groupHistories = new Map<string, HistoryEntry[]>();
 
       const stopFn = startTeamilyMonitoring(account, async (message) => {
+        try {
         const rt = getTeamilyRuntime();
         const currentCfg = rt.config.loadConfig();
 
         const isGroup = isGroupSession(message.sessionType);
         const from = message.sendID;
+        const rawText = message.content?.text || "";
 
         log?.info?.(
           `[${accountId}] Incoming message: sessionType=${message.sessionType}, isGroup=${isGroup}, ` +
           `from=${from}, recvID=${message.recvID}, isAtSelf=${message.isAtSelf ?? false}`,
         );
 
-        // In group chats, all messages are dispatched to the agent for context,
-        // but only @-mentioned messages trigger a reply.
-        const shouldReply = !isGroup || !!message.isAtSelf;
+        const historyKey = isGroup ? `teamily:group:${message.recvID}` : undefined;
+
+        // In group chats, buffer non-@-mention messages for context and skip dispatch.
+        // Only @-mention messages are dispatched to the agent, with the buffer injected.
+        if (isGroup && !message.isAtSelf) {
+          if (historyKey && rawText) {
+            recordPendingHistoryEntryIfEnabled({
+              historyMap: groupHistories,
+              historyKey,
+              limit: historyLimit,
+              entry: {
+                sender: from,
+                body: rawText,
+                timestamp: message.sendTime,
+              },
+            });
+          }
+          return;
+        }
 
-        const text = message.content?.text || "";
         const sessionKey = isGroup ? `teamily:group:${message.recvID}` : `teamily:${from}`;
 
         let mediaUrl: string | undefined;
@@ -287,9 +311,21 @@ export const teamilyPlugin: ChannelPlugin<ResolvedTeamilyAccount> = {
           }
         }
 
+        // For group @-mention messages, prepend buffered history as context.
+        const body =
+          isGroup && historyKey
+            ? buildPendingHistoryContextFromMap({
+                historyMap: groupHistories,
+                historyKey,
+                limit: historyLimit,
+                currentMessage: rawText,
+                formatEntry: (entry) => `${entry.sender}: ${entry.body}`,
+              })
+            : rawText;
+
         const replyTarget = isGroup ? `group:${message.recvID}` : from;
         const msgCtx = {
-          Body: text,
+          Body: body,
           From: from,
           To: account.userID,
           SessionKey: sessionKey,
@@ -304,12 +340,15 @@ export const teamilyPlugin: ChannelPlugin<ResolvedTeamilyAccount> = {
           MediaType: mediaType,
         };
 
+        log?.info?.(
+          `[${accountId}] Dispatching reply: sessionKey=${sessionKey}, chatType=${isGroup ? "group" : "direct"}, replyTarget=${replyTarget}`,
+        );
+
         await rt.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
           ctx: msgCtx,
           cfg: currentCfg,
           dispatcherOptions: {
             deliver: async (payload: { text?: string; body?: string }) => {
-              if (!shouldReply) return;
               const replyText = payload?.text ?? payload?.body;
               if (replyText) {
                 const monitor = getTeamilyMonitor(accountId);
@@ -324,6 +363,22 @@ export const teamilyPlugin: ChannelPlugin<ResolvedTeamilyAccount> = {
             },
           },
         });
+
+        log?.info?.(`[${accountId}] Dispatch completed for ${sessionKey}`);
+
+        // Clear history buffer after dispatch so context doesn't repeat.
+        if (isGroup && historyKey) {
+          clearHistoryEntriesIfEnabled({
+            historyMap: groupHistories,
+            historyKey,
+            limit: historyLimit,
+          });
+        }
+        } catch (err) {
+          log?.error?.(
+            `[${accountId}] Error handling message from ${message.sendID}: ${err instanceof Error ? err.stack || err.message : String(err)}`,
+          );
+        }
       });
 
       // Respect abort signal from the gateway framework