@ascegu/teamily 1.0.18 → 1.0.19

package/README.md

@@ -1,6 +1,6 @@
 # Teamily Channel Plugin for OpenClaw
 
-Integrates [Teamily](https://teamily.ai/) (based on OpenIM) with OpenClaw as a self-hosted team messaging channel.
+Integrates [Teamily](https://teamily.ai/) with OpenClaw as a self-hosted team messaging channel.
 
 ## Installation
 
@@ -28,9 +28,9 @@ openclaw channel configure teamily
 
 | 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`    |
+| `platformUrl` | Teamily platform URL     | `https://imserver-test.teamily.ai/im_api`  |
+| `apiURL`      | Teamily REST API URL     | `https://imserver-test.teamily.ai/im_api`  |
+| `wsURL`       | Teamily WebSocket URL    | `wss://imserver-test.teamily.ai/msg_gateway`    |
 
 ### Bot Account Settings
 
@@ -57,9 +57,9 @@ channels:
   teamily:
     enabled: true
     server:
-      platformUrl: http://your-server:10002
-      apiURL: http://your-server:10002
-      wsURL: ws://your-server:10001
+      platformUrl: https://imserver-test.teamily.ai/im_api
+      apiURL: https://imserver-test.teamily.ai/im_api
+      wsURL: wss://imserver-test.teamily.ai/msg_gateway
     accounts:
       default:
         userID: "bot-user-id"
@@ -100,8 +100,8 @@ Supported media types are auto-detected by file extension:
 
 ## Group Chat Behavior
 
-- 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.
+- All group messages are received and dispatched to the agent for context accumulation.
+- The bot only **replies** when it is **@-mentioned** in the group (`@BotName`).
 - In direct messages, the bot always replies.
 - Both regular groups (`sessionType=3`) and super groups (`sessionType=2`) are supported.
 
@@ -114,7 +114,6 @@ Supported media types are auto-detected by file extension:
 | 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       |
@@ -122,12 +121,6 @@ Supported media types are auto-detected by file extension:
 | Threads                   | No        |
 | Polls                     | No        |
 
-## Setting Up Teamily Server
-
-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.
-
 ## Architecture
 
 ```
@@ -144,10 +137,6 @@ src/
   send.ts             REST API message/media send (fallback path)
 ```
 
-## Compatibility
-
-Designed for OpenIM API v2/v3. Requires `@openim/client-sdk` ^3.8.3.
-
 ## License
 
 MIT

package/package.json

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

package/src/channel.ts

@@ -0,0 +1,453 @@
+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,
+  createScopedAccountConfigAccessors,
+} from "openclaw/plugin-sdk/compat";
+import {
+  listTeamilyAccountIds,
+  resolveDefaultTeamilyAccountId,
+  resolveTeamilyAccount,
+} from "./accounts.js";
+import { TeamilyConfigSchema } from "./config-schema.js";
+import type { CoreConfig } from "./config-schema.js";
+import { getTeamilyMonitor, startTeamilyMonitoring, stopTeamilyMonitoring } from "./monitor.js";
+import { normalizeTeamilyTarget, normalizeTeamilyAllowEntry } from "./normalize.js";
+import { probeTeamily } from "./probe.js";
+import { getTeamilyRuntime } from "./runtime.js";
+import type { ResolvedTeamilyAccount } from "./types.js";
+import { isGroupSession } from "./types.js";
+
+const meta = {
+  id: "teamily",
+  label: "Teamily",
+  selectionLabel: "Teamily (self-hosted)",
+  docsPath: "/channels/teamily",
+  docsLabel: "teamily",
+  blurb: "Team instant messaging server",
+  order: 75,
+  quickstartAllowFrom: true,
+};
+
+const teamilyConfigAccessors = createScopedAccountConfigAccessors({
+  resolveAccount: ({ cfg, accountId }) => resolveTeamilyAccount(cfg as CoreConfig, accountId),
+  resolveAllowFrom: (account) => account.dm?.allowFrom,
+  formatAllowFrom: (allowFrom) => allowFrom.map((id) => String(id)),
+});
+
+export const teamilyPlugin: ChannelPlugin<ResolvedTeamilyAccount> = {
+  id: "teamily",
+  meta,
+  capabilities: {
+    chatTypes: ["direct", "group"],
+    media: true,
+    reactions: false,
+    threads: false,
+    polls: false,
+  },
+  reload: { configPrefixes: ["channels.teamily"] },
+  setup: {
+    resolveAccountId: ({ accountId, input }) => {
+      if (accountId) return accountId;
+      if (input?.name) return normalizeAccountId(String(input.name));
+      return DEFAULT_ACCOUNT_ID;
+    },
+    applyAccountName: ({ cfg, accountId, name }) =>
+      applyAccountNameToChannelSection({
+        cfg,
+        channelKey: "teamily",
+        accountId,
+        name,
+      }),
+    applyAccountConfig: ({ cfg, accountId, input }) =>
+      applyTeamilyAccountConfig({
+        cfg: cfg as CoreConfig,
+        accountId,
+        input: input as Record<string, unknown>,
+      }),
+  },
+  pairing: {
+    idLabel: "teamilyUserId",
+    normalizeAllowEntry: (entry) => {
+      try {
+        return normalizeTeamilyAllowEntry(entry);
+      } catch {
+        return entry;
+      }
+    },
+    notifyApproval: async ({ id, cfg }) => {
+      try {
+        const accountId = resolveDefaultTeamilyAccountId(cfg as CoreConfig);
+        const target = normalizeTeamilyTarget(id);
+        const monitor = getTeamilyMonitor(accountId);
+        if (monitor) {
+          await monitor.sendText(target, PAIRING_APPROVED_MESSAGE);
+        }
+        // If monitor isn't running, skip silently — pairing was still approved
+      } catch {
+        // Silently fail on notification
+      }
+    },
+  },
+  configSchema: buildChannelConfigSchema(TeamilyConfigSchema),
+  config: {
+    listAccountIds: (cfg) => listTeamilyAccountIds(cfg as CoreConfig),
+    resolveAccount: (cfg, accountId) => resolveTeamilyAccount(cfg as CoreConfig, accountId),
+    defaultAccountId: (cfg) => resolveDefaultTeamilyAccountId(cfg as CoreConfig),
+    setAccountEnabled: ({ cfg, accountId, enabled }) =>
+      setAccountEnabledInConfigSection({
+        cfg: cfg as CoreConfig,
+        sectionKey: "teamily",
+        accountId,
+        enabled,
+        allowTopLevel: true,
+      }),
+    deleteAccount: ({ cfg, accountId }) =>
+      deleteAccountFromConfigSection({
+        cfg: cfg as CoreConfig,
+        sectionKey: "teamily",
+        accountId,
+        clearBaseFields: ["name", "userID", "token", "nickname", "faceURL"],
+      }),
+    isConfigured: (account) => !!account.token,
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      name: account.nickname || account.userID,
+      enabled: account.enabled,
+      configured: !!account.token,
+    }),
+    ...teamilyConfigAccessors,
+  },
+  security: {
+    resolveDmPolicy: ({ cfg, accountId, account }) => {
+      return buildAccountScopedDmSecurityPolicy({
+        cfg: cfg as CoreConfig,
+        channelKey: "teamily",
+        accountId,
+        fallbackAccountId: account.accountId ?? DEFAULT_ACCOUNT_ID,
+        policy: account.dm?.policy,
+        allowFrom: account.dm?.allowFrom ?? [],
+        allowFromPathSuffix: "dm.",
+        normalizeEntry: (raw) => normalizeTeamilyAllowEntry(raw),
+      });
+    },
+  },
+  outbound: {
+    deliveryMode: "gateway",
+    resolveTarget: ({ to }) => {
+      if (!to?.trim()) {
+        return { ok: false, error: new Error("Teamily requires --to <userId|group:groupId>") };
+      }
+      try {
+        const target = normalizeTeamilyTarget(to);
+        // Preserve the full target format so sendText/sendMedia can distinguish user vs group
+        const resolved = target.type === "group" ? `group:${target.id}` : target.id;
+        return { ok: true, to: resolved };
+      } catch (err) {
+        return { ok: false, error: err instanceof Error ? err : new Error(String(err)) };
+      }
+    },
+    sendText: async (ctx: ChannelOutboundContext) => {
+      const { to, text, accountId } = ctx;
+      const monitor = requireMonitor(accountId);
+      const target = normalizeTeamilyTarget(to);
+      const messageId = await monitor.sendText(target, text);
+      return { channel: "teamily" as const, messageId };
+    },
+    sendMedia: async (ctx: ChannelOutboundContext) => {
+      const { to, accountId } = ctx;
+      const mediaUrl = ctx.mediaUrl;
+      if (!mediaUrl) {
+        throw new Error("Media URL is required");
+      }
+      const monitor = requireMonitor(accountId);
+      const target = normalizeTeamilyTarget(to);
+
+      let messageId: string;
+      const urlLower = mediaUrl.toLowerCase();
+      if (urlLower.endsWith(".mp4") || urlLower.endsWith(".mov") || urlLower.endsWith(".webm")) {
+        messageId = await monitor.sendVideo(target, mediaUrl);
+      } else if (urlLower.endsWith(".mp3") || urlLower.endsWith(".m4a") || urlLower.endsWith(".wav")) {
+        messageId = await monitor.sendAudio(target, mediaUrl);
+      } else if (urlLower.endsWith(".pdf") || urlLower.endsWith(".doc") || urlLower.endsWith(".docx") || urlLower.endsWith(".zip")) {
+        messageId = await monitor.sendFile(target, mediaUrl);
+      } else {
+        messageId = await monitor.sendImage(target, mediaUrl);
+      }
+
+      return { channel: "teamily" as const, messageId };
+    },
+  },
+  status: {
+    probeAccount: async ({ account }) => {
+      const result = await probeTeamily(account);
+      if (!result.connected) {
+        return {
+          ok: false,
+          error: result.error || "Failed to connect to Teamily server",
+        };
+      }
+      return { ok: true };
+    },
+    buildAccountSnapshot: ({ account, runtime, probe }) => ({
+      accountId: account.accountId,
+      name: account.nickname || account.userID,
+      enabled: account.enabled,
+      configured: !!account.token,
+      running: runtime?.running ?? false,
+      lastStartAt: runtime?.lastStartAt ?? null,
+      lastStopAt: runtime?.lastStopAt ?? null,
+      lastError: runtime?.lastError ?? null,
+      probe,
+    }),
+    collectStatusIssues: (accounts) => {
+      const issues: ChannelStatusIssue[] = [];
+      for (const snap of accounts) {
+        if (snap.lastError) {
+          issues.push({
+            channel: "teamily",
+            accountId: snap.accountId,
+            kind: "runtime",
+            message: snap.lastError,
+            fix: "Check that the Teamily server is running and accessible",
+          });
+        }
+      }
+      return issues;
+    },
+  },
+  gateway: {
+    startAccount: async (ctx) => {
+      const { accountId, account, log } = ctx;
+
+      if (!account.token) {
+        log?.warn?.(`Teamily account ${accountId} not configured (missing token)`);
+        return;
+      }
+
+      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}`,
+        );
+
+        const historyKey = isGroup ? `teamily:group:${message.recvID}` : undefined;
+
+        // In group chats, buffer non-@-mention text-only messages for context.
+        // Media messages (picture/video/audio) are always dispatched — OpenIM sends
+        // @-mention text and media as separate messages, so a PICTURE following an
+        // AT_TEXT won't have isAtSelf=true. Dispatching media keeps group image
+        // handling consistent with DM behavior.
+        const hasMedia = !!(
+          message.content?.picture ||
+          message.content?.video ||
+          message.content?.audio
+        );
+        if (isGroup && !message.isAtSelf && !hasMedia) {
+          if (historyKey && rawText) {
+            recordPendingHistoryEntryIfEnabled({
+              historyMap: groupHistories,
+              historyKey,
+              limit: historyLimit,
+              entry: {
+                sender: from,
+                body: rawText,
+                timestamp: message.sendTime,
+              },
+            });
+          }
+          return;
+        }
+
+        const sessionKey = isGroup ? `teamily:group:${message.recvID}` : `teamily:${from}`;
+
+        let mediaUrl: string | undefined;
+        if (message.content?.picture?.sourcePicture?.url) {
+          mediaUrl = message.content.picture.sourcePicture.url;
+        } else if (message.content?.video?.videoUrl) {
+          mediaUrl = message.content.video.videoUrl;
+        } else if (message.content?.audio?.sourceUrl) {
+          mediaUrl = message.content.audio.sourceUrl;
+        }
+
+        // Download remote media to a local temp file so the agent recognises
+        // image-only messages (hasMediaAttachment checks MediaPath, not MediaUrl).
+        let mediaPath: string | undefined;
+        let mediaType: string | undefined;
+        if (mediaUrl) {
+          try {
+            const fetched = await rt.channel.media.fetchRemoteMedia({ url: mediaUrl, maxBytes: MEDIA_MAX_BYTES });
+            const saved = await rt.channel.media.saveMediaBuffer(
+              fetched.buffer,
+              fetched.contentType,
+              "inbound",
+              MEDIA_MAX_BYTES,
+            );
+            mediaPath = saved.path;
+            mediaType = saved.contentType;
+          } catch (err) {
+            log?.warn?.(`[${accountId}] Failed to download Teamily media: ${String(err)}`);
+          }
+        }
+
+        // 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: body,
+          From: from,
+          To: account.userID,
+          SessionKey: sessionKey,
+          AccountId: accountId,
+          Provider: "teamily" as const,
+          Surface: "teamily" as const,
+          OriginatingChannel: "teamily" as const,
+          OriginatingTo: replyTarget,
+          ChatType: isGroup ? "group" : "direct",
+          MediaUrl: mediaUrl,
+          MediaPath: mediaPath,
+          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 }) => {
+              const replyText = payload?.text ?? payload?.body;
+              if (replyText) {
+                const monitor = getTeamilyMonitor(accountId);
+                if (!monitor) throw new Error(`Teamily monitor not running for account ${accountId}`);
+                log?.info?.(`[${accountId}] Sending reply to: ${replyTarget} (isGroup=${isGroup})`);
+                const target = normalizeTeamilyTarget(replyTarget);
+                await monitor.sendText(target, replyText);
+              }
+            },
+            onReplyStart: () => {
+              log?.info?.(`Agent reply started for ${from}`);
+            },
+          },
+        });
+
+        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
+      ctx.abortSignal.addEventListener("abort", () => {
+        stopFn();
+        stopTeamilyMonitoring(accountId);
+      });
+
+      // Block until aborted — monitor runs indefinitely
+      await new Promise<void>((resolve) => {
+        ctx.abortSignal.addEventListener("abort", () => resolve());
+      });
+    },
+  },
+};
+
+function applyTeamilyAccountConfig(params: {
+  cfg: CoreConfig;
+  accountId: string;
+  input: Record<string, unknown>;
+}): CoreConfig {
+  const { cfg, accountId, input } = params;
+  const existing = cfg.channels?.teamily;
+  const server = existing?.server ?? { platformUrl: "", apiURL: "", wsURL: "" };
+  const accounts = existing?.accounts ?? {};
+
+  const accountUpdate: Record<string, unknown> = {};
+  if (input.userID) accountUpdate.userID = String(input.userID);
+  if (input.token) accountUpdate.token = String(input.token);
+  if (input.nickname) accountUpdate.nickname = String(input.nickname);
+  if (input.faceURL) accountUpdate.faceURL = String(input.faceURL);
+
+  const serverUpdate: Record<string, string> = {};
+  if (input.platformUrl) serverUpdate.platformUrl = String(input.platformUrl);
+  if (input.apiURL) serverUpdate.apiURL = String(input.apiURL);
+  if (input.wsURL) serverUpdate.wsURL = String(input.wsURL);
+
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      teamily: {
+        enabled: true,
+        server: { ...server, ...serverUpdate },
+        accounts: {
+          ...accounts,
+          [accountId]: {
+            ...accounts[accountId],
+            ...accountUpdate,
+          },
+        },
+      },
+    },
+  } as CoreConfig;
+}
+
+function requireMonitor(accountId?: string | null) {
+  const id = accountId || "default";
+  const monitor = getTeamilyMonitor(id);
+  if (!monitor) {
+    throw new Error(`Teamily gateway not running for account "${id}" — outbound requires an active gateway`);
+  }
+  return monitor;
+}