openclaw-ringcentral 2026.1.30-beta.1 → 2026.1.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-ringcentral",
-  "version": "2026.1.30-beta.1",
+  "version": "2026.1.30",
   "type": "module",
   "main": "index.ts",
   "description": "OpenClaw RingCentral Team Messaging channel plugin",
@@ -57,6 +57,7 @@
     }
   },
   "dependencies": {
+    "@rc-ex/ws": "^1.0.0",
     "@ringcentral/sdk": "^5.0.0",
     "@ringcentral/subscriptions": "^5.0.0",
     "isomorphic-ws": "^5.0.0",

package/src/accounts.ts

@@ -139,7 +139,7 @@ export function resolveRingCentralAccount(params: {
   cfg: OpenClawConfig;
   accountId?: string | null;
 }): ResolvedRingCentralAccount {
-  const accountId = normalizeAccountId(params.accountId);
+  const accountId = normalizeAccountId(params.accountId ?? undefined);
   const baseEnabled =
     (params.cfg.channels?.ringcentral as RingCentralConfig | undefined)?.enabled !== false;
   const merged = mergeRingCentralAccountConfig(params.cfg, accountId);

package/src/api.ts

@@ -12,6 +12,100 @@ import type {
 // Team Messaging API endpoints
 const TM_API_BASE = "/team-messaging/v1";
 
+export type RingCentralApiErrorInfo = {
+  httpStatus?: number;
+  requestId?: string;
+  errorCode?: string;
+  errorMessage?: string;
+  accountId?: string;
+  errors?: Array<{ errorCode?: string; message?: string; parameterName?: string }>;
+};
+
+export function extractRcApiError(err: unknown, accountId?: string): RingCentralApiErrorInfo {
+  const info: RingCentralApiErrorInfo = {};
+  if (accountId) info.accountId = accountId;
+
+  if (!err || typeof err !== "object") {
+    info.errorMessage = String(err);
+    return info;
+  }
+
+  const e = err as Record<string, unknown>;
+
+  // @ringcentral/sdk wraps errors with response object
+  const response = e.response as Record<string, unknown> | undefined;
+  if (response) {
+    info.httpStatus = typeof response.status === "number" ? response.status : undefined;
+    
+    // Extract request ID from headers
+    const headers = response.headers as Record<string, unknown> | undefined;
+    if (headers) {
+      // headers can be a Headers object or plain object
+      if (typeof (headers as any).get === "function") {
+        info.requestId = (headers as any).get("x-request-id") ?? (headers as any).get("rcrequestid");
+      } else {
+        info.requestId = (headers["x-request-id"] ?? headers["rcrequestid"]) as string | undefined;
+      }
+    }
+  }
+
+  // Try to extract error body (SDK often attaches parsed JSON to error)
+  const body = (e._response as Record<string, unknown> | undefined) ?? 
+               (e.body as Record<string, unknown> | undefined) ??
+               (e.data as Record<string, unknown> | undefined);
+  if (body && typeof body === "object") {
+    info.errorCode = body.errorCode as string | undefined;
+    info.errorMessage = body.message as string | undefined;
+    if (Array.isArray(body.errors)) {
+      info.errors = body.errors;
+    }
+  }
+
+  // Fallback: parse message if it looks like JSON
+  if (!info.errorCode && typeof e.message === "string") {
+    const msg = e.message;
+    try {
+      const parsed = JSON.parse(msg);
+      if (parsed && typeof parsed === "object") {
+        info.errorCode = parsed.errorCode;
+        info.errorMessage = parsed.message ?? info.errorMessage;
+        if (Array.isArray(parsed.errors)) {
+          info.errors = parsed.errors;
+        }
+      }
+    } catch {
+      // Not JSON, use as-is
+      info.errorMessage = info.errorMessage ?? msg;
+    }
+  }
+
+  // Extract from standard Error properties
+  if (!info.errorMessage && typeof e.message === "string") {
+    info.errorMessage = e.message;
+  }
+
+  return info;
+}
+
+export function formatRcApiError(info: RingCentralApiErrorInfo): string {
+  const parts: string[] = [];
+  
+  if (info.httpStatus) parts.push(`HTTP ${info.httpStatus}`);
+  if (info.errorCode) parts.push(`ErrorCode=${info.errorCode}`);
+  if (info.requestId) parts.push(`RequestId=${info.requestId}`);
+  if (info.accountId) parts.push(`AccountId=${info.accountId}`);
+  if (info.errorMessage) parts.push(`Message="${info.errorMessage}"`);
+  
+  if (info.errors && info.errors.length > 0) {
+    const errDetails = info.errors
+      .map((e) => `${e.errorCode ?? "?"}: ${e.message ?? "?"}${e.parameterName ? ` (${e.parameterName})` : ""}`)
+      .join("; ");
+    parts.push(`Details=[${errDetails}]`);
+  }
+  
+  return parts.length > 0 ? parts.join(" | ") : "Unknown error";
+}
+
 export async function sendRingCentralMessage(params: {
   account: ResolvedRingCentralAccount;
   chatId: string;
@@ -132,7 +226,7 @@ export async function uploadRingCentralAttachment(params: {
 
   // Create FormData for multipart upload
   const formData = new FormData();
-  const blob = new Blob([buffer], { type: contentType || "application/octet-stream" });
+  const blob = new Blob([new Uint8Array(buffer)], { type: contentType || "application/octet-stream" });
   formData.append("file", blob, filename);
 
   const response = await platform.post(

package/src/channel.ts

@@ -74,7 +74,7 @@ export const ringcentralDock: ChannelDock = {
     resolveReplyToMode: ({ cfg }) =>
       (cfg.channels?.ringcentral as RingCentralConfig | undefined)?.replyToMode ?? "off",
     buildToolContext: ({ context, hasRepliedRef }) => ({
-      currentChannelId: context.To?.trim() || undefined,
+      currentChannelId: (context.To as string | undefined)?.trim() || undefined,
       currentThreadTs: undefined,
       hasRepliedRef,
     }),
@@ -305,7 +305,7 @@ export const ringcentralPlugin: ChannelPlugin<ResolvedRingCentralAccount> = {
         cfg: cfg as OpenClawConfig,
         channelKey: "ringcentral",
         accountId,
-        name: input.name,
+        name: input.name as string | undefined,
       });
       const next =
         accountId !== DEFAULT_ACCOUNT_ID
@@ -315,6 +315,7 @@ export const ringcentralPlugin: ChannelPlugin<ResolvedRingCentralAccount> = {
             })
           : namedConfig;
       // Build nested credentials block
+      const inputServer = input.server as string | undefined;
       const credentialsPatch = input.useEnv
         ? {}
         : {
@@ -322,11 +323,11 @@ export const ringcentralPlugin: ChannelPlugin<ResolvedRingCentralAccount> = {
               ...(input.clientId ? { clientId: input.clientId } : {}),
               ...(input.clientSecret ? { clientSecret: input.clientSecret } : {}),
               ...(input.jwt ? { jwt: input.jwt } : {}),
-              ...(input.server?.trim() ? { server: input.server.trim() } : {}),
+              ...(inputServer?.trim() ? { server: inputServer.trim() } : {}),
             },
           };
       // Only include credentials if it has any values
-      const hasCredentials = input.clientId || input.clientSecret || input.jwt || input.server?.trim();
+      const hasCredentials = input.clientId || input.clientSecret || input.jwt || inputServer?.trim();
       const configPatch = input.useEnv || !hasCredentials ? {} : credentialsPatch;
       if (accountId === DEFAULT_ACCOUNT_ID) {
         return {

package/src/monitor.ts

@@ -1,4 +1,7 @@
 import { Subscriptions } from "@ringcentral/subscriptions";
+import RcWsExtension, { Events as RcWsEvents } from "@rc-ex/ws";
+const WebSocketExtension = RcWsExtension.default ?? RcWsExtension;
+type WebSocketExtension = InstanceType<typeof WebSocketExtension>;
 
 import type { OpenClawConfig } from "openclaw/plugin-sdk";
 import { resolveMentionGatingWithBypass } from "openclaw/plugin-sdk";
@@ -12,6 +15,8 @@ import {
   downloadRingCentralAttachment,
   uploadRingCentralAttachment,
   getRingCentralChat,
+  extractRcApiError,
+  formatRcApiError,
 } from "./api.js";
 import { getRingCentralRuntime } from "./runtime.js";
 import type {
@@ -47,6 +52,88 @@ const RECONNECT_MAX_DELAY = 300000; // 5 minutes (increased for rate limiting)
 const RECONNECT_MAX_ATTEMPTS = 5; // Reduced attempts
 const RATE_LIMIT_BACKOFF = 60000; // 1 minute backoff on 429
 
+// WebSocket singleton per account to avoid hammering /oauth/wstoken.
+// @ringcentral/subscriptions + @rc-ex/ws can swallow initial connect errors and
+// repeated new Subscriptions()/newWsExtension() will trigger new wstoken calls.
+type WsManager = {
+  key: string;
+  sdk: any;
+  subscriptions: Subscriptions;
+  rc: any;
+  wsExt: WebSocketExtension;
+  connectPromise?: Promise<void>;
+  lastConnectAt?: number;
+};
+
+const wsManagers = new Map<string, WsManager>();
+
+function buildWsManagerKey(account: ResolvedRingCentralAccount): string {
+  // Changes in credentials should force a new WS manager.
+  return `${account.clientId}:${account.server}:${account.jwt?.slice(0, 20)}`;
+}
+
+async function getOrCreateWsManager(
+  account: ResolvedRingCentralAccount,
+  logger: RingCentralLogger,
+): Promise<WsManager> {
+  const key = buildWsManagerKey(account);
+  const cached = wsManagers.get(account.accountId);
+  if (cached && cached.key === key) return cached;
+
+  // Replace cache entry on credential change.
+  const sdk = await getRingCentralSDK(account);
+  const subscriptions = new Subscriptions({ sdk });
+  await (subscriptions as any).init?.();
+
+  const wsExt = new WebSocketExtension({
+    debugMode: true,
+    autoRecover: { enabled: false },
+  });
+
+  const rc = (subscriptions as any).rc;
+  if (!rc || typeof rc.installExtension !== "function") {
+    throw new Error("Subscriptions.rc.installExtension is unavailable; cannot install WS extension");
+  }
+
+  logger.debug(`[${account.accountId}] Installing @rc-ex/ws extension (singleton)...`);
+  await rc.installExtension(wsExt);
+
+  const mgr: WsManager = { key, sdk, subscriptions, rc, wsExt };
+  wsManagers.set(account.accountId, mgr);
+  return mgr;
+}
+
+async function ensureWsConnected(
+  mgr: WsManager,
+  account: ResolvedRingCentralAccount,
+  logger: RingCentralLogger,
+): Promise<void> {
+  // If already connected/open, nothing to do.
+  const ws = mgr.wsExt.ws;
+  if (ws && (ws.readyState === 0 || ws.readyState === 1)) {
+    return;
+  }
+  if (mgr.connectPromise) {
+    return mgr.connectPromise;
+  }
+
+  mgr.connectPromise = (async () => {
+    logger.debug(`[${account.accountId}] Forcing WS connect() (singleton)...`);
+    await mgr.wsExt.connect(false);
+    mgr.lastConnectAt = Date.now();
+    if (!mgr.wsExt.ws) {
+      throw new Error("WS connect() returned but wsExt.ws is still undefined");
+    }
+  })();
+
+  try {
+    await mgr.connectPromise;
+  } finally {
+    mgr.connectPromise = undefined;
+  }
+}
+
+
 function trackSentMessageId(messageId: string): void {
   recentlySentMessageIds.add(messageId);
   setTimeout(() => recentlySentMessageIds.delete(messageId), MESSAGE_ID_TTL);
@@ -195,6 +282,7 @@ async function processMessageWithPipeline(params: {
   ownerId?: string;
 }): Promise<void> {
   const { eventBody, account, config, runtime, core, statusSink, ownerId } = params;
+  const logger = getLogger(core);
   const mediaMaxMb = account.config.mediaMaxMb ?? 20;
   
   const chatId = eventBody.groupId ?? "";
@@ -225,7 +313,7 @@ async function processMessageWithPipeline(params: {
   // This is because the bot uses the JWT user's identity, so we're essentially
   // having a conversation with ourselves (the AI assistant)
   const selfOnly = account.config.selfOnly !== false; // default true
-  runtime.log?.(`[${account.accountId}] Processing message: senderId=${senderId}, ownerId=${ownerId}, selfOnly=${selfOnly}, chatId=${chatId}`);
+  logger.debug(`[${account.accountId}] Processing message: senderId=${senderId}, ownerId=${ownerId}, selfOnly=${selfOnly}, chatId=${chatId}`);
   
   if (selfOnly && ownerId) {
     if (senderId !== ownerId) {
@@ -234,7 +322,7 @@ async function processMessageWithPipeline(params: {
     }
   }
   
-  runtime.log?.(`[${account.accountId}] Message passed selfOnly check`);
+  logger.debug(`[${account.accountId}] Message passed selfOnly check`);
 
   // Fetch chat info to determine type
   let chatType = "Group";
@@ -250,7 +338,7 @@ async function processMessageWithPipeline(params: {
   // Personal, PersonalChat, Direct are all DM types
   const isPersonalChat = chatType === "Personal" || chatType === "PersonalChat";
   const isGroup = chatType !== "Direct" && chatType !== "PersonalChat" && chatType !== "Personal";
-  runtime.log?.(`[${account.accountId}] Chat type: ${chatType}, isGroup: ${isGroup}`);
+  logger.debug(`[${account.accountId}] Chat type: ${chatType}, isGroup: ${isGroup}`);
 
   // In selfOnly mode, only allow "Personal" chat (conversation with yourself)
   if (selfOnly && !isPersonalChat) {
@@ -281,7 +369,6 @@ async function processMessageWithPipeline(params: {
       if (!groupAllowlistConfigured) {
         logVerbose(
           core,
-          runtime,
           `drop group message (groupPolicy=allowlist, no allowlist, chat=${chatId})`,
         );
         return;
@@ -452,11 +539,11 @@ async function processMessageWithPipeline(params: {
   void core.channel.session
     .recordSessionMetaFromInbound({
       storePath,
-      sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+      sessionKey: (ctxPayload.SessionKey as string | undefined) ?? route.sessionKey,
       ctx: ctxPayload,
     })
     .catch((err) => {
-      runtime.error?.(`ringcentral: failed updating session meta: ${String(err)}`);
+      logger.error(`ringcentral: failed updating session meta: ${String(err)}`);
     });
 
   // Typing indicator disabled - respond directly without "thinking" message
@@ -470,7 +557,6 @@ async function processMessageWithPipeline(params: {
           payload,
           account,
           chatId,
-          runtime,
           core,
           config,
           statusSink,
@@ -478,7 +564,7 @@ async function processMessageWithPipeline(params: {
         });
       },
       onError: (err, info) => {
-        runtime.error?.(
+        logger.error(
           `[${account.accountId}] RingCentral ${info.kind} reply failed: ${String(err)}`,
         );
       },
@@ -510,13 +596,13 @@ async function deliverRingCentralReply(params: {
   payload: { text?: string; mediaUrls?: string[]; mediaUrl?: string };
   account: ResolvedRingCentralAccount;
   chatId: string;
-  runtime: RingCentralRuntimeEnv;
   core: RingCentralCoreRuntime;
   config: OpenClawConfig;
   statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
   typingPostId?: string;
 }): Promise<void> {
-  const { payload, account, chatId, runtime, core, config, statusSink, typingPostId } = params;
+  const { payload, account, chatId, core, config, statusSink, typingPostId } = params;
+  const logger = getLogger(core);
   const mediaList = payload.mediaUrls?.length
     ? payload.mediaUrls
     : payload.mediaUrl
@@ -533,7 +619,8 @@ async function deliverRingCentralReply(params: {
           postId: typingPostId,
         });
       } catch (err) {
-        runtime.error?.(`RingCentral typing cleanup failed: ${String(err)}`);
+        const errInfo = formatRcApiError(extractRcApiError(err, account.accountId));
+        logger.error(`RingCentral typing cleanup failed: ${errInfo}`);
         const fallbackText = payload.text?.trim()
           ? payload.text
           : mediaList.length > 1
@@ -548,7 +635,8 @@ async function deliverRingCentralReply(params: {
           });
           suppressCaption = Boolean(payload.text?.trim());
         } catch (updateErr) {
-          runtime.error?.(`RingCentral typing update failed: ${String(updateErr)}`);
+          const updateErrInfo = formatRcApiError(extractRcApiError(updateErr, account.accountId));
+          logger.error(`RingCentral typing update failed: ${updateErrInfo}`);
         }
       }
     }
@@ -579,7 +667,8 @@ async function deliverRingCentralReply(params: {
         if (sendResult?.postId) trackSentMessageId(sendResult.postId);
         statusSink?.({ lastOutboundAt: Date.now() });
       } catch (err) {
-        runtime.error?.(`RingCentral attachment send failed: ${String(err)}`);
+        const errInfo = formatRcApiError(extractRcApiError(err, account.accountId));
+        logger.error(`RingCentral attachment send failed: ${errInfo}`);
       }
     }
     return;
@@ -618,7 +707,8 @@ async function deliverRingCentralReply(params: {
         }
         statusSink?.({ lastOutboundAt: Date.now() });
       } catch (err) {
-        runtime.error?.(`RingCentral message send failed: ${String(err)}`);
+        const errInfo = formatRcApiError(extractRcApiError(err, account.accountId));
+        logger.error(`RingCentral message send failed: ${errInfo}`);
       }
     }
   }
@@ -637,6 +727,9 @@ export async function startRingCentralMonitor(
   let isShuttingDown = false;
   let ownerId: string | undefined;
 
+  // Avoid hammering /oauth/wstoken (auth rate limit is very low, e.g. 5/min).
+  let nextAllowedWsConnectAt = 0;
+
   // Calculate delay with exponential backoff
   const getReconnectDelay = () => {
     const delay = Math.min(
@@ -652,18 +745,47 @@ export async function startRingCentralMonitor(
 
     logger.info(`[${account.accountId}] Starting RingCentral WebSocket subscription...`);
 
+    if (Date.now() < nextAllowedWsConnectAt) {
+      const waitMs = nextAllowedWsConnectAt - Date.now();
+      logger.warn(
+        `[${account.accountId}] WS connect is rate-limited locally; will retry in ${Math.ceil(waitMs / 1000)}s`,
+      );
+      scheduleReconnect();
+      return;
+    }
+
     try {
-      // Get SDK instance
-      const sdk = await getRingCentralSDK(account);
-      
-      // Create subscriptions manager
-      const subscriptions = new Subscriptions({ sdk });
-      const subscription = subscriptions.createSubscription();
+      // Get or create WS manager (singleton per account)
+      const mgr = await getOrCreateWsManager(account, logger);
+
+      // Force connect once per account (with in-flight de-dupe)
+      await ensureWsConnected(mgr, account, logger);
+
+      const subscription = mgr.subscriptions.createSubscription();
+
+      // IMPORTANT: @ringcentral/subscriptions will create *its own* WS extension instance internally
+      // when calling subscription.register(), which can still lead to `wse.ws` undefined and
+      // addEventListener crash. We bypass it by using our singleton wsExt directly.
+      // We'll keep `subscription` object for event emitter convenience, but registration uses wsExt.
+
+
+      // Extra diagnostics: log versions so we can pin a working combo.
+      try {
+        // @ts-ignore - dynamic import of package.json for version logging
+        const sdkVer = (await import("@ringcentral/sdk/package.json", { with: { type: "json" } } as any))?.default?.version;
+        // @ts-ignore - dynamic import of package.json for version logging
+        const subsVer = (await import("@ringcentral/subscriptions/package.json", { with: { type: "json" } } as any))?.default?.version;
+        // @ts-ignore - dynamic import of package.json for version logging
+        const rcwsVer = (await import("@rc-ex/ws/package.json", { with: { type: "json" } } as any))?.default?.version;
+        logger.debug(`[${account.accountId}] rc sdk versions: @ringcentral/sdk=${sdkVer} @ringcentral/subscriptions=${subsVer} @rc-ex/ws=${rcwsVer}`);
+      } catch {
+        // ignore
+      }
 
       // Track current user ID to filter out self messages
       if (!ownerId) {
         try {
-          const platform = sdk.platform();
+          const platform = mgr.sdk.platform();
           const response = await platform.get("/restapi/v1.0/account/~/extension/~");
           const userInfo = await response.json();
           ownerId = userInfo?.id?.toString();
@@ -691,30 +813,57 @@ export async function startRingCentralMonitor(
       });
 
       // Subscribe to Team Messaging events and save WsSubscription for cleanup
-      wsSubscription = await subscription
-        .setEventFilters([
-          "/restapi/v1.0/glip/posts",
-          "/restapi/v1.0/glip/groups",
-        ])
-        .register();
+      // Register subscription via singleton wsExt (NOT via @ringcentral/subscriptions.register()).
+      // This avoids newWsExtension() being created per call.
+      const eventFilters = [
+        "/restapi/v1.0/glip/posts",
+        "/restapi/v1.0/glip/groups",
+      ];
+      wsSubscription = await mgr.wsExt.subscribe(eventFilters, (event: unknown) => {
+        subscription.emit(subscription.events.notification, event);
+      });
       
       logger.info(`[${account.accountId}] RingCentral WebSocket subscription established`);
       reconnectAttempts = 0; // Reset on success
 
     } catch (err) {
+      const e = err as any;
       const errStr = String(err);
-      logger.error(`[${account.accountId}] Failed to create WebSocket subscription: ${errStr}`);
-      
-      // Check for rate limiting (429) or auth errors
-      const isRateLimited = errStr.includes("429") || errStr.includes("rate") || errStr.includes("Rate");
+      const msg = e?.stack ? String(e.stack) : errStr;
+
+      // Check for auth errors - don't retry on auth failures
       const isAuthError = errStr.includes("401") || errStr.includes("Unauthorized") || errStr.includes("invalid_grant");
-      
       if (isAuthError) {
         logger.error(`[${account.accountId}] Authentication failed. Please check your credentials.`);
-        // Don't retry on auth errors - they won't self-resolve
         return;
       }
-      
+
+      // If we hit auth rate limit for /oauth/wstoken, back off according to retry-after.
+      const retryAfterHeader =
+        typeof e?.response?.headers?.get === "function" ? e.response.headers.get("retry-after") :
+        typeof e?.response?.headers?.["retry-after"] === "string" ? e.response.headers["retry-after"] :
+        undefined;
+      const retryAfterMs =
+        typeof e?.retryAfter === "number" ? e.retryAfter :
+        (retryAfterHeader ? (parseInt(retryAfterHeader, 10) * 1000) : undefined);
+
+      const isRateLimited = e?.message === "Request rate exceeded" || e?.response?.status === 429 ||
+        errStr.includes("429") || errStr.includes("rate") || errStr.includes("Rate");
+
+      if (isRateLimited) {
+        const backoffMs = Number.isFinite(retryAfterMs) && retryAfterMs! > 0 ? retryAfterMs! : RATE_LIMIT_BACKOFF;
+        nextAllowedWsConnectAt = Date.now() + backoffMs;
+        logger.error(
+          `[${account.accountId}] WS connect failed due to rate limit (wstoken). ` +
+            `Backing off for ${Math.ceil(backoffMs / 1000)}s before retrying.`,
+        );
+      }
+
+      logger.error(
+        `[${account.accountId}] WS subscription failed. ` +
+          `Reason=${e?.name ?? 'Error'}: ${e?.message ?? errStr}\n` +
+          `Stack:\n${msg}`,
+      );
       scheduleReconnect(isRateLimited);
     }
   };

package/src/openclaw.d.ts

@@ -1,9 +1,39 @@
 declare module "openclaw/plugin-sdk" {
   import { z } from "zod";
 
-  // Types
+  // Agent Types
+  export type AgentConfig = {
+    id: string;
+    name?: string;
+    [key: string]: unknown;
+  };
+
+  // Base Types
   export type OpenClawConfig = {
-    channels?: Record<string, unknown>;
+    channels?: {
+      defaults?: {
+        groupPolicy?: GroupPolicy;
+        [key: string]: unknown;
+      };
+      ringcentral?: {
+        enabled?: boolean;
+        accounts?: Record<string, unknown>;
+        [key: string]: unknown;
+      };
+      [key: string]: unknown;
+    };
+    agents?: {
+      list?: AgentConfig[];
+      [key: string]: unknown;
+    };
+    commands?: {
+      useAccessGroups?: boolean;
+      [key: string]: unknown;
+    };
+    session?: {
+      store?: string;
+      [key: string]: unknown;
+    };
     [key: string]: unknown;
   };
 
@@ -20,47 +50,344 @@ declare module "openclaw/plugin-sdk" {
     error: (message: string) => void;
   };
 
+  // Channel Runtime Types
+  export type ChannelRuntime = {
+    text: {
+      chunkMarkdownText: (text: string, limit: number) => string[];
+      chunkMarkdownTextWithMode: (text: string, limit: number, mode: string) => string[];
+      resolveChunkMode: (config: OpenClawConfig, channel: string, accountId: string) => string;
+      hasControlCommand: (body: string, config: OpenClawConfig) => boolean;
+    };
+    media: {
+      fetchRemoteMedia: (url: string, opts: { maxBytes?: number }) => Promise<{
+        buffer: Buffer;
+        filename?: string;
+        contentType?: string;
+      }>;
+      saveTempMedia: (opts: { buffer: Buffer; contentType?: string; filename?: string }) => Promise<string>;
+      saveMediaBuffer: (buffer: Buffer, contentType: string | undefined, direction: string, maxBytes: number, filename?: string) => Promise<{ path: string; contentType?: string }>;
+    };
+    commands: {
+      shouldComputeCommandAuthorized: (body: string, config: OpenClawConfig) => boolean;
+      shouldHandleTextCommands: (opts: { cfg: OpenClawConfig; surface: string }) => boolean;
+      isControlCommandMessage: (body: string, config: OpenClawConfig) => boolean;
+      resolveCommandAuthorizedFromAuthorizers: (opts: {
+        useAccessGroups: boolean;
+        authorizers: Array<{ configured: boolean; allowed: boolean }>;
+      }) => boolean | undefined;
+    };
+    pairing: {
+      readAllowFromStore: (channel: string) => Promise<string[]>;
+    };
+    routing: {
+      resolveAgentRoute: (opts: {
+        cfg: OpenClawConfig;
+        channel: string;
+        accountId: string;
+        peer: { kind: string; id: string };
+      }) => { agentId: string; sessionKey: string; accountId: string };
+    };
+    session: {
+      resolveStorePath: (store: string | undefined, opts: { agentId: string }) => string;
+      readSessionUpdatedAt: (opts: { storePath: string; sessionKey: string }) => number | undefined;
+      recordSessionMetaFromInbound: (opts: { storePath: string; sessionKey: string; ctx: Record<string, unknown> }) => Promise<void>;
+    };
+    reply: {
+      resolveEnvelopeFormatOptions: (config: OpenClawConfig) => Record<string, unknown>;
+      formatAgentEnvelope: (opts: {
+        channel: string;
+        from: string;
+        timestamp?: number;
+        previousTimestamp?: number;
+        envelope: Record<string, unknown>;
+        body: string;
+      }) => string;
+      finalizeInboundContext: (payload: Record<string, unknown>) => Record<string, unknown>;
+      dispatchReplyWithBufferedBlockDispatcher: (opts: {
+        ctx: Record<string, unknown>;
+        cfg: OpenClawConfig;
+        dispatcherOptions: {
+          deliver: (payload: { text?: string; mediaUrl?: string; error?: Error }) => Promise<void>;
+          onError: (err: unknown, info: { kind: string }) => void;
+        };
+      }) => Promise<void>;
+    };
+    inbound: {
+      handleInbound: (opts: {
+        channel: string;
+        context: Record<string, unknown>;
+        replyFn: (response: { message?: string; error?: Error }, info: Record<string, unknown>) => Promise<void>;
+        agentRoute?: { agentId: string; sessionKey: string };
+        sessionPath?: string;
+        groupSystemPrompt?: string;
+        abortSignal?: AbortSignal;
+      }) => Promise<void>;
+    };
+    groups: {
+      resolveGroupConfig: (opts: {
+        channel: string;
+        groupId: string;
+        accountId: string;
+        cfg: OpenClawConfig;
+      }) => {
+        isAllowed: boolean;
+        allowlist: string[];
+        users: string[];
+        entry?: { requireMention?: boolean; systemPrompt?: string; [key: string]: unknown };
+      };
+    };
+  };
+
   export type PluginRuntime = {
     logging: {
       shouldLogVerbose: () => boolean;
       getChildLogger: (bindings: Record<string, unknown>, opts?: { level?: string }) => PluginLogger;
     };
+    channel: ChannelRuntime;
     [key: string]: unknown;
   };
 
-  export type ChannelPlugin = {
-    id: string;
+  // Policy Types
+  export type DmPolicy = "open" | "allowlist" | "pairing" | "disabled";
+  export type GroupPolicy = "open" | "allowlist" | "disabled";
+  export type MarkdownConfig = {
+    enabled?: boolean;
     [key: string]: unknown;
   };
 
+  // Channel Dock Type
   export type ChannelDock = {
     id: string;
-    [key: string]: unknown;
+    capabilities: {
+      chatTypes: string[];
+      reactions: boolean;
+      media: boolean;
+      threads: boolean;
+      blockStreaming: boolean;
+    };
+    outbound?: {
+      textChunkLimit?: number;
+    };
+    config?: {
+      resolveAllowFrom?: (opts: { cfg: OpenClawConfig; accountId: string }) => string[];
+      formatAllowFrom?: (opts: { allowFrom: string[] }) => string[];
+    };
+    groups?: {
+      resolveRequireMention?: (opts: { cfg: OpenClawConfig; accountId: string }) => boolean;
+    };
+    threading?: {
+      resolveReplyToMode?: (opts: { cfg: OpenClawConfig }) => string;
+      buildToolContext?: (opts: { context: Record<string, unknown>; hasRepliedRef: { current: boolean } }) => Record<string, unknown>;
+    };
   };
 
-  export type DmPolicy = "open" | "allowlist" | "disabled";
-  export type GroupPolicy = "open" | "allowlist" | "disabled";
-  export type MarkdownConfig = {
-    enabled?: boolean;
-    [key: string]: unknown;
+  // Channel Plugin Types
+  export type ChannelPluginMeta = {
+    id: string;
+    label: string;
+    selectionLabel?: string;
+    docsPath?: string;
+    docsLabel?: string;
+    blurb?: string;
+    order?: number;
+  };
+
+  export type ChannelPluginCapabilities = {
+    chatTypes: string[];
+    reactions: boolean;
+    threads: boolean;
+    media: boolean;
+    nativeCommands?: boolean;
+    blockStreaming?: boolean;
+  };
+
+  export type ChannelPluginPairing<TAccount> = {
+    idLabel: string;
+    normalizeAllowEntry: (entry: string) => string;
+    notifyApproval: (opts: { cfg: OpenClawConfig; id: string; account?: TAccount }) => Promise<void>;
+  };
+
+  export type ChannelPluginConfig<TAccount> = {
+    listAccountIds: (cfg: OpenClawConfig) => string[];
+    resolveAccount: (cfg: OpenClawConfig, accountId?: string) => TAccount;
+    defaultAccountId: (cfg: OpenClawConfig) => string;
+    setAccountEnabled: (opts: { cfg: OpenClawConfig; accountId: string; enabled: boolean }) => OpenClawConfig;
+    deleteAccount: (opts: { cfg: OpenClawConfig; accountId: string }) => OpenClawConfig;
+    isConfigured: (account: TAccount) => boolean;
+    describeAccount: (account: TAccount) => Record<string, unknown>;
+    resolveAllowFrom: (opts: { cfg: OpenClawConfig; accountId: string }) => string[];
+    formatAllowFrom: (opts: { allowFrom: string[] }) => string[];
+  };
+
+  export type ChannelPluginSecurity<TAccount> = {
+    resolveDmPolicy: (opts: { cfg: OpenClawConfig; accountId?: string; account: TAccount }) => {
+      policy: DmPolicy;
+      allowFrom: (string | number)[];
+      allowFromPath: string;
+      approveHint: string;
+      normalizeEntry: (raw: string) => string;
+    };
+    collectWarnings: (opts: { account: TAccount; cfg: OpenClawConfig }) => string[];
+  };
+
+  export type ChannelPluginGroups = {
+    resolveRequireMention: (opts: { cfg: OpenClawConfig; accountId: string }) => boolean;
+  };
+
+  export type ChannelPluginThreading = {
+    resolveReplyToMode: (opts: { cfg: OpenClawConfig }) => string;
+  };
+
+  export type ChannelPluginMessaging = {
+    normalizeTarget: (target: string) => string | null;
+    targetResolver: {
+      looksLikeId: (raw: string, normalized: string | null) => boolean;
+      hint: string;
+    };
+  };
+
+  export type DirectoryPeer = { kind: "user"; id: string };
+  export type DirectoryGroup = { kind: "group"; id: string };
+
+  export type ChannelPluginDirectory<TAccount> = {
+    self: (opts: { account: TAccount }) => Promise<{ id: string; name?: string } | null>;
+    listPeers: (opts: { cfg: OpenClawConfig; accountId: string; query?: string; limit?: number }) => Promise<DirectoryPeer[]>;
+    listGroups: (opts: { cfg: OpenClawConfig; accountId: string; query?: string; limit?: number }) => Promise<DirectoryGroup[]>;
+  };
+
+  export type ResolvedTarget = { input: string; resolved: boolean; id?: string; note?: string };
+
+  export type ChannelPluginResolver = {
+    resolveTargets: (opts: { inputs: string[]; kind: "user" | "group" }) => Promise<ResolvedTarget[]>;
+  };
+
+  export type ChannelPluginSetup = {
+    resolveAccountId: (opts: { accountId?: string }) => string;
+    applyAccountName: (opts: { cfg: OpenClawConfig; accountId: string; name?: string }) => OpenClawConfig;
+    validateInput: (opts: { accountId: string; input: Record<string, unknown> }) => string | null;
+    applyAccountConfig: (opts: { cfg: OpenClawConfig; accountId: string; input: Record<string, unknown> }) => OpenClawConfig;
+  };
+
+  export type OutboundResult = {
+    channel: string;
+    messageId: string;
+    chatId: string;
+  };
+
+  export type ChannelPluginOutbound<TAccount> = {
+    deliveryMode: "direct" | "queued";
+    chunker: (text: string, limit: number) => string[];
+    chunkerMode?: "markdown" | "plain";
+    textChunkLimit: number;
+    resolveTarget: (opts: { to?: string; allowFrom?: string[]; mode?: string }) => { ok: true; to: string } | { ok: false; error: Error };
+    sendText: (opts: { cfg: OpenClawConfig; to: string; text: string; accountId?: string }) => Promise<OutboundResult>;
+    sendMedia: (opts: { cfg: OpenClawConfig; to: string; text?: string; mediaUrl?: string; accountId?: string }) => Promise<OutboundResult>;
+  };
+
+  export type StatusIssue = {
+    channel: string;
+    accountId: string;
+    kind: string;
+    message: string;
+    fix?: string;
+  };
+
+  export type ChannelPluginStatus<TAccount> = {
+    defaultRuntime: Record<string, unknown>;
+    collectStatusIssues: (accounts: Array<Record<string, unknown>>) => StatusIssue[];
+    buildChannelSummary: (opts: { snapshot: Record<string, unknown> }) => Record<string, unknown>;
+    probeAccount: (opts: { account: TAccount }) => Promise<{ ok: boolean; error?: string; elapsedMs: number }>;
+    buildAccountSnapshot: (opts: { account: TAccount; runtime?: Record<string, unknown>; probe?: Record<string, unknown> }) => Record<string, unknown>;
+  };
+
+  export type GatewayContext<TAccount> = {
+    account: TAccount;
+    cfg: OpenClawConfig;
+    runtime: { log?: (msg: string) => void; error?: (msg: string) => void; info?: (msg: string) => void };
+    abortSignal: AbortSignal;
+    setStatus: (patch: Record<string, unknown>) => void;
+    log?: PluginLogger;
+  };
+
+  export type ChannelPluginGateway<TAccount> = {
+    startAccount: (ctx: GatewayContext<TAccount>) => Promise<() => void>;
+  };
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  export type ChannelPlugin<TAccount = any> = {
+    id: string;
+    meta: ChannelPluginMeta;
+    pairing?: ChannelPluginPairing<TAccount>;
+    capabilities: ChannelPluginCapabilities;
+    streaming?: {
+      blockStreamingCoalesceDefaults?: { minChars?: number; idleMs?: number };
+    };
+    reload?: {
+      configPrefixes?: string[];
+    };
+    configSchema: z.ZodType<unknown>;
+    config: ChannelPluginConfig<TAccount>;
+    security?: ChannelPluginSecurity<TAccount>;
+    groups?: ChannelPluginGroups;
+    threading?: ChannelPluginThreading;
+    messaging?: ChannelPluginMessaging;
+    directory?: ChannelPluginDirectory<TAccount>;
+    resolver?: ChannelPluginResolver;
+    setup?: ChannelPluginSetup;
+    outbound: ChannelPluginOutbound<TAccount>;
+    status?: ChannelPluginStatus<TAccount>;
+    gateway?: ChannelPluginGateway<TAccount>;
   };
 
   // Constants
   export const DEFAULT_ACCOUNT_ID: string;
 
   // Functions
-  export function normalizeAccountId(accountId: string | undefined): string;
+  export function normalizeAccountId(accountId: string | null | undefined): string;
   export function emptyPluginConfigSchema(): z.ZodObject<Record<string, never>>;
-  export function resolveMentionGatingWithBypass(opts: unknown): unknown;
+  export function resolveMentionGatingWithBypass(opts: {
+    isGroup: boolean;
+    requireMention: boolean;
+    canDetectMention: boolean;
+    wasMentioned: boolean;
+    implicitMention: boolean;
+    hasAnyMention: boolean;
+    allowTextCommands: boolean;
+    hasControlCommand: boolean;
+    commandAuthorized: boolean;
+  }): { shouldSkip: boolean; effectiveWasMentioned?: boolean };
   export function requireOpenAllowFrom(opts: unknown): void;
-  export function applyAccountNameToChannelSection(opts: unknown): unknown;
-  export function buildChannelConfigSchema(opts: unknown): unknown;
-  export function deleteAccountFromConfigSection(opts: unknown): unknown;
-  export function formatPairingApproveHint(opts: unknown): string;
-  export function migrateBaseNameToDefaultAccount(opts: unknown): unknown;
-  export function missingTargetError(opts: unknown): Error;
-  export function setAccountEnabledInConfigSection(opts: unknown): unknown;
-  export function resolveChannelMediaMaxBytes(opts: unknown): number;
+  export function applyAccountNameToChannelSection(opts: {
+    cfg: OpenClawConfig;
+    channelKey: string;
+    accountId: string;
+    name?: string;
+  }): OpenClawConfig;
+  export function buildChannelConfigSchema(schema: z.ZodType<unknown>): z.ZodType<unknown>;
+  export function deleteAccountFromConfigSection(opts: {
+    cfg: OpenClawConfig;
+    sectionKey: string;
+    accountId: string;
+    clearBaseFields?: string[];
+  }): OpenClawConfig;
+  export function formatPairingApproveHint(channel: string): string;
+  export function migrateBaseNameToDefaultAccount(opts: {
+    cfg: OpenClawConfig;
+    channelKey: string;
+  }): OpenClawConfig;
+  export function missingTargetError(channel: string, hint: string): Error;
+  export function setAccountEnabledInConfigSection(opts: {
+    cfg: OpenClawConfig;
+    sectionKey: string;
+    accountId: string;
+    enabled: boolean;
+    allowTopLevel?: boolean;
+  }): OpenClawConfig;
+  export function resolveChannelMediaMaxBytes(opts: {
+    cfg: OpenClawConfig;
+    resolveChannelLimitMb: (opts: { cfg: OpenClawConfig; accountId: string }) => number | undefined;
+    accountId?: string;
+  }): number | undefined;
 
   // Constants for messages
   export const PAIRING_APPROVED_MESSAGE: string;