@shenhh/popo-native 0.1.0

package/src/monitor.ts

@@ -0,0 +1,261 @@
+import http from "http";
+import { registerPluginHttpRoute, normalizePluginHttpPath } from "openclaw/plugin-sdk";
+import type { ClawdbotConfig, RuntimeEnv, HistoryEntry } from "openclaw/plugin-sdk";
+import type { PopoNativeConfig } from "./types.js";
+import { resolvePopoNativeCredentials } from "./accounts.js";
+import { verifySignature, decryptMessage, encryptMessage } from "./crypto.js";
+import { handlePopoNativeMessage, type PopoNativeMessageEvent } from "./bot.js";
+import { probePopoNative } from "./probe.js";
+import { configureSubscription } from "./subscription.js";
+
+export type MonitorPopoNativeOpts = {
+  config?: ClawdbotConfig;
+  runtime?: RuntimeEnv;
+  abortSignal?: AbortSignal;
+  accountId?: string;
+};
+
+// Helper function to read request body
+function readRequestBody(req: http.IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    req.on("data", (chunk) => chunks.push(chunk));
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+    req.on("error", reject);
+  });
+}
+
+export async function monitorPopoNativeProvider(opts: MonitorPopoNativeOpts = {}): Promise<void> {
+  const cfg = opts.config;
+  if (!cfg) {
+    throw new Error("Config is required for POPO Native monitor");
+  }
+
+  const popoCfg = cfg.channels?.["popo-native"] as PopoNativeConfig | undefined;
+  const creds = resolvePopoNativeCredentials(popoCfg);
+  if (!creds) {
+    throw new Error("POPO Native credentials not configured (appId, appSecret required)");
+  }
+
+  const log = opts.runtime?.log ?? console.log;
+  const error = opts.runtime?.error ?? console.error;
+
+  // Verify credentials by getting a token
+  const probeResult = await probePopoNative(popoCfg);
+  if (!probeResult.ok) {
+    throw new Error(`POPO Native probe failed: ${probeResult.error}`);
+  }
+  log(`popo-native: credentials verified for appId ${probeResult.appId}`);
+
+  const webhookPath = popoCfg?.webhookPath?.trim() || "/popo-native/events";
+  const chatHistories = new Map<string, HistoryEntry[]>();
+
+  // Normalize path
+  const normalizedPath = normalizePluginHttpPath(webhookPath, "/popo-native/events") ?? "/popo-native/events";
+
+  // Configure event subscription if subscription config is provided
+  if (popoCfg?.subscription) {
+    try {
+      const webhookUrl = `${cfg.server?.publicUrl ?? ""}${normalizedPath}`;
+      const subResult = await configureSubscription({
+        cfg,
+        webhookUrl,
+        uid: popoCfg.subscription.robotUid,
+        authTypes: popoCfg.subscription.authTypes,
+        teams: popoCfg.subscription.teams,
+      });
+      if (subResult.success) {
+        log(`popo-native: event subscription configured successfully`);
+      } else {
+        error(`popo-native: failed to configure event subscription: ${subResult.error}`);
+      }
+    } catch (err) {
+      error(`popo-native: error configuring subscription: ${String(err)}`);
+    }
+  }
+
+  // Register HTTP route to gateway
+  const unregisterHttp = registerPluginHttpRoute({
+    path: normalizedPath,
+    pluginId: "popo-native",
+    accountId: opts.accountId,
+    log: (msg: string) => log(msg),
+    handler: async (req, res) => {
+      const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+      log(`popo-native: received ${req.method} request to ${url.pathname}`);
+
+      // Handle CORS preflight
+      if (req.method === "OPTIONS") {
+        res.writeHead(200, {
+          "Access-Control-Allow-Origin": "*",
+          "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+          "Access-Control-Allow-Headers": "Content-Type, Authorization",
+        });
+        res.end();
+        return;
+      }
+
+      // Handle URL validation (GET request)
+      if (req.method === "GET") {
+        const nonce = url.searchParams.get("nonce");
+        const timestamp = url.searchParams.get("timestamp");
+        const signature = url.searchParams.get("signature");
+
+        log(`popo-native: URL validation attempt - nonce=${nonce}, timestamp=${timestamp}, signature=${signature}`);
+
+        if (nonce && timestamp && signature && creds.token) {
+          const valid = verifySignature({
+            token: creds.token,
+            nonce,
+            timestamp,
+            signature,
+          });
+
+          if (valid) {
+            log(`popo-native: URL validation successful`);
+            res.writeHead(200, { "Content-Type": "text/plain" });
+            res.end(nonce);
+            return;
+          } else {
+            log(`popo-native: signature verification failed`);
+          }
+        } else {
+          log(`popo-native: missing required parameters for validation`);
+        }
+
+        res.writeHead(400);
+        res.end("Invalid validation request");
+        return;
+      }
+
+      // Handle webhook event (POST request)
+      if (req.method === "POST") {
+        try {
+          const body = await readRequestBody(req);
+          const payload = JSON.parse(body);
+
+          // Check for encrypted payload
+          let eventData: unknown;
+          if (payload.encrypt && creds.aesKey) {
+            // Verify signature first
+            const { nonce, timestamp, signature } = payload;
+            if (nonce && timestamp && signature && creds.token) {
+              const valid = verifySignature({
+                token: creds.token,
+                nonce,
+                timestamp,
+                signature,
+              });
+
+              if (!valid) {
+                log(`popo-native: invalid signature in webhook event`);
+                res.writeHead(403);
+                res.end("Invalid signature");
+                return;
+              }
+            }
+
+            // Decrypt the message
+            const decrypted = decryptMessage(payload.encrypt, creds.aesKey);
+            eventData = JSON.parse(decrypted);
+          } else {
+            eventData = payload;
+          }
+
+          const event = eventData as { eventType?: string };
+
+          // Handle valid_url event
+          if (event.eventType === "valid_url") {
+            log(`popo-native: received valid_url event`);
+            const response = { eventType: "valid_url" };
+
+            if (creds.aesKey) {
+              const encrypted = encryptMessage(JSON.stringify(response), creds.aesKey);
+              res.writeHead(200, { "Content-Type": "application/json" });
+              res.end(JSON.stringify({ encrypt: encrypted }));
+            } else {
+              res.writeHead(200, { "Content-Type": "application/json" });
+              res.end(JSON.stringify(response));
+            }
+            return;
+          }
+
+          // Handle MSG_SEND events (native API event type)
+          if (event.eventType === "MSG_SEND") {
+            const messageEvent = eventData as PopoNativeMessageEvent;
+            log(`popo-native: received MSG_SEND event`);
+
+            // Process message asynchronously
+            handlePopoNativeMessage({
+              cfg,
+              event: messageEvent,
+              runtime: opts.runtime,
+              chatHistories,
+            }).catch((err) => {
+              error(`popo-native: error handling message: ${String(err)}`);
+            });
+          }
+
+          // Handle MSG_RECALL events
+          if (event.eventType === "MSG_RECALL") {
+            log(`popo-native: received MSG_RECALL event`);
+            // TODO: Handle message recall if needed
+          }
+
+          // Handle ACTION events (card interactions)
+          if (event.eventType === "ACTION") {
+            log(`popo-native: received ACTION event`);
+            // TODO: Implement card action handling if needed
+          }
+
+          // Return success response
+          const successResponse = { success: true };
+          if (creds.aesKey) {
+            const encrypted = encryptMessage(JSON.stringify(successResponse), creds.aesKey);
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ encrypt: encrypted }));
+          } else {
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify(successResponse));
+          }
+        } catch (err) {
+          error(`popo-native: error processing webhook: ${String(err)}`);
+          res.writeHead(500);
+          res.end("Internal Server Error");
+        }
+        return;
+      }
+
+      res.writeHead(405);
+      res.end("Method Not Allowed");
+    },
+  });
+
+  log(`popo-native: registered webhook handler at ${normalizedPath}`);
+
+  // Handle abort signal
+  const stopHandler = () => {
+    log("popo-native: stopping provider");
+    unregisterHttp();
+  };
+
+  if (opts.abortSignal?.aborted) {
+    stopHandler();
+    return;
+  }
+
+  opts.abortSignal?.addEventListener("abort", stopHandler, { once: true });
+
+  // Keep promise pending until abort
+  return new Promise((resolve) => {
+    const handler = () => {
+      stopHandler();
+      resolve();
+    };
+
+    if (opts.abortSignal) {
+      opts.abortSignal.removeEventListener("abort", stopHandler);
+      opts.abortSignal.addEventListener("abort", handler, { once: true });
+    }
+  });
+}

package/src/outbound.ts

@@ -0,0 +1,138 @@
+import type { ChannelOutboundAdapter } from "openclaw/plugin-sdk";
+import { getPopoNativeRuntime } from "./runtime.js";
+import {
+  sendMessagePopoNative,
+  sendCardPopoNative,
+  createStreamCardPopoNative,
+  updateStreamCardPopoNative,
+} from "./send.js";
+import { sendMediaPopoNative } from "./media.js";
+
+export const popoNativeOutbound: ChannelOutboundAdapter = {
+  deliveryMode: "direct",
+  chunker: (text, limit) => getPopoNativeRuntime().channel.text.chunkMarkdownText(text, limit),
+  chunkerMode: "markdown",
+  textChunkLimit: 4000,
+  sendText: async ({ cfg, to, text }) => {
+    const result = await sendMessagePopoNative({ cfg, to, text });
+    return { channel: "popo-native", ...result };
+  },
+  sendMedia: async ({ cfg, to, text, mediaUrl }) => {
+    // Send text first if provided
+    if (text?.trim()) {
+      await sendMessagePopoNative({ cfg, to, text });
+    }
+
+    // Upload and send media if URL provided
+    if (mediaUrl) {
+      try {
+        const result = await sendMediaPopoNative({ cfg, to, mediaUrl });
+        return { channel: "popo-native", ...result };
+      } catch (err) {
+        // Log the error for debugging
+        console.error(`[popo-native] sendMediaPopoNative failed:`, err);
+        // Fallback to URL link if upload fails
+        const fallbackText = `📎 ${mediaUrl}`;
+        const result = await sendMessagePopoNative({ cfg, to, text: fallbackText });
+        return { channel: "popo-native", ...result };
+      }
+    }
+
+    // No media URL, just return text result
+    const result = await sendMessagePopoNative({ cfg, to, text: text ?? "" });
+    return { channel: "popo-native", ...result };
+  },
+
+  sendCard: async ({ cfg, to, card }) => {
+    const {
+      templateUuid,
+      instanceUuid,
+      callBackConfigKey,
+      publicVariableMap,
+      batchPrivateVariableMap,
+      options,
+    } = card as {
+      templateUuid: string;
+      instanceUuid: string;
+      callBackConfigKey?: string;
+      publicVariableMap?: Record<string, unknown>;
+      batchPrivateVariableMap?: Record<string, Record<string, unknown>>;
+      options?: import("./send.js").PopoNativeCardOptions;
+    };
+    const result = await sendCardPopoNative({
+      cfg,
+      to,
+      templateUuid,
+      instanceUuid,
+      callBackConfigKey,
+      publicVariableMap,
+      batchPrivateVariableMap,
+      options,
+    });
+    return { channel: "popo-native", ...result };
+  },
+
+  // Streaming card support
+  createStreamCard: async ({ cfg, to, card }) => {
+    const {
+      templateUuid,
+      instanceUuid,
+      robotAccount,
+      fromUser,
+      sessionType,
+      callbackKey,
+      initialContent,
+    } = card as {
+      templateUuid: string;
+      instanceUuid: string;
+      robotAccount: string;
+      fromUser?: string;
+      sessionType?: number;
+      callbackKey?: string;
+      initialContent?: string;
+    };
+    const result = await createStreamCardPopoNative({
+      cfg,
+      to,
+      templateUuid,
+      instanceUuid,
+      robotAccount,
+      fromUser,
+      sessionType,
+      callbackKey,
+      initialContent,
+    });
+    return { channel: "popo-native", success: result.success, instanceUuid: result.instanceUuid };
+  },
+
+  updateStreamCard: async ({ cfg, card }) => {
+    const {
+      templateUuid,
+      instanceUuid,
+      content,
+      sequence,
+      isFinalize,
+      isError,
+      streamKey,
+    } = card as {
+      templateUuid: string;
+      instanceUuid: string;
+      content: string;
+      sequence: number;
+      isFinalize?: boolean;
+      isError?: boolean;
+      streamKey?: string;
+    };
+    const result = await updateStreamCardPopoNative({
+      cfg,
+      templateUuid,
+      instanceUuid,
+      content,
+      sequence,
+      isFinalize,
+      isError,
+      streamKey,
+    });
+    return { channel: "popo-native", success: result.success };
+  },
+};

package/src/policy.ts

@@ -0,0 +1,93 @@
+import type { ChannelGroupContext, GroupToolPolicyConfig } from "openclaw/plugin-sdk";
+import type { PopoNativeConfig } from "./types.js";
+import type { PopoNativeGroupConfig } from "./config-schema.js";
+
+export type PopoNativeAllowlistMatch = {
+  allowed: boolean;
+  matchKey?: string;
+  matchSource?: "wildcard" | "id" | "name";
+};
+
+export function resolvePopoNativeAllowlistMatch(params: {
+  allowFrom: Array<string | number>;
+  senderId: string;
+  senderName?: string | null;
+}): PopoNativeAllowlistMatch {
+  const allowFrom = params.allowFrom
+    .map((entry) => String(entry).trim().toLowerCase())
+    .filter(Boolean);
+
+  if (allowFrom.length === 0) return { allowed: false };
+  if (allowFrom.includes("*")) {
+    return { allowed: true, matchKey: "*", matchSource: "wildcard" };
+  }
+
+  const senderId = params.senderId.toLowerCase();
+  if (allowFrom.includes(senderId)) {
+    return { allowed: true, matchKey: senderId, matchSource: "id" };
+  }
+
+  const senderName = params.senderName?.toLowerCase();
+  if (senderName && allowFrom.includes(senderName)) {
+    return { allowed: true, matchKey: senderName, matchSource: "name" };
+  }
+
+  return { allowed: false };
+}
+
+export function resolvePopoNativeGroupConfig(params: {
+  cfg?: PopoNativeConfig;
+  groupId?: string | null;
+}): PopoNativeGroupConfig | undefined {
+  const groups = params.cfg?.groups ?? {};
+  const groupId = params.groupId?.trim();
+  if (!groupId) return undefined;
+
+  const direct = groups[groupId] as PopoNativeGroupConfig | undefined;
+  if (direct) return direct;
+
+  const lowered = groupId.toLowerCase();
+  const matchKey = Object.keys(groups).find((key) => key.toLowerCase() === lowered);
+  return matchKey ? (groups[matchKey] as PopoNativeGroupConfig | undefined) : undefined;
+}
+
+export function resolvePopoNativeGroupToolPolicy(
+  params: ChannelGroupContext
+): GroupToolPolicyConfig | undefined {
+  const cfg = params.cfg.channels?.["popo-native"] as PopoNativeConfig | undefined;
+  if (!cfg) return undefined;
+
+  const groupConfig = resolvePopoNativeGroupConfig({
+    cfg,
+    groupId: params.groupId,
+  });
+
+  return groupConfig?.tools;
+}
+
+export function isPopoNativeGroupAllowed(params: {
+  groupPolicy: "open" | "allowlist" | "disabled";
+  allowFrom: Array<string | number>;
+  senderId: string;
+  senderName?: string | null;
+}): boolean {
+  const { groupPolicy } = params;
+  if (groupPolicy === "disabled") return false;
+  if (groupPolicy === "open") return true;
+  return resolvePopoNativeAllowlistMatch(params).allowed;
+}
+
+export function resolvePopoNativeReplyPolicy(params: {
+  isDirectMessage: boolean;
+  globalConfig?: PopoNativeConfig;
+  groupConfig?: PopoNativeGroupConfig;
+}): { requireMention: boolean } {
+  if (params.isDirectMessage) {
+    return { requireMention: false };
+  }
+
+  const requireMention =
+    params.groupConfig?.requireMention ?? params.globalConfig?.requireMention ?? true;
+
+  return { requireMention };
+}

package/src/probe.ts

@@ -0,0 +1,29 @@
+import type { PopoNativeConfig, PopoNativeProbeResult } from "./types.js";
+import { resolvePopoNativeCredentials } from "./accounts.js";
+import { getAccessToken } from "./auth.js";
+
+export async function probePopoNative(cfg?: PopoNativeConfig): Promise<PopoNativeProbeResult> {
+  const creds = resolvePopoNativeCredentials(cfg);
+  if (!creds) {
+    return {
+      ok: false,
+      error: "missing credentials (appId, appSecret)",
+    };
+  }
+
+  try {
+    // Try to get an access token to verify credentials
+    await getAccessToken(cfg!);
+
+    return {
+      ok: true,
+      appId: creds.appId,
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      appId: creds.appId,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}

package/src/reply-dispatcher.ts

@@ -0,0 +1,126 @@
+import {
+  createReplyPrefixContext,
+  createTypingCallbacks,
+  logTypingFailure,
+  type ClawdbotConfig,
+  type RuntimeEnv,
+  type ReplyPayload,
+} from "openclaw/plugin-sdk";
+import { getPopoNativeRuntime } from "./runtime.js";
+import { sendMessagePopoNative } from "./send.js";
+import type { PopoNativeConfig } from "./types.js";
+
+export type CreatePopoNativeReplyDispatcherParams = {
+  cfg: ClawdbotConfig;
+  agentId: string;
+  runtime: RuntimeEnv;
+  sessionId: string;
+};
+
+export function createPopoNativeReplyDispatcher(params: CreatePopoNativeReplyDispatcherParams) {
+  const core = getPopoNativeRuntime();
+  const { cfg, agentId, sessionId } = params;
+
+  const prefixContext = createReplyPrefixContext({
+    cfg,
+    agentId,
+  });
+
+  // Track whether any tool results have been sent
+  let hasToolResults = false;
+  let toolResultCount = 0;
+
+  // POPO doesn't have a native typing indicator API
+  const typingCallbacks = createTypingCallbacks({
+    start: async () => {
+      // No-op for POPO
+    },
+    stop: async () => {
+      // No-op for POPO
+    },
+    onStartError: (err) => {
+      logTypingFailure({
+        log: (message) => params.runtime.log?.(message),
+        channel: "popo-native",
+        action: "start",
+        error: err,
+      });
+    },
+    onStopError: (err) => {
+      logTypingFailure({
+        log: (message) => params.runtime.log?.(message),
+        channel: "popo-native",
+        action: "stop",
+        error: err,
+      });
+    },
+  });
+
+  const textChunkLimit = core.channel.text.resolveTextChunkLimit({
+    cfg,
+    channel: "popo-native",
+    defaultLimit: 4000,
+  });
+  const chunkMode = core.channel.text.resolveChunkMode(cfg, "popo-native");
+
+  const { dispatcher, replyOptions, markDispatchIdle } =
+    core.channel.reply.createReplyDispatcherWithTyping({
+      responsePrefix: prefixContext.responsePrefix,
+      responsePrefixContextProvider: prefixContext.responsePrefixContextProvider,
+      humanDelay: core.channel.reply.resolveHumanDelayConfig(cfg, agentId),
+      onReplyStart: typingCallbacks.onReplyStart,
+      deliver: async (payload: ReplyPayload) => {
+        params.runtime.log?.(`popo-native deliver called: text=${payload.text?.slice(0, 100)}`);
+        const text = payload.text ?? "";
+
+        // Build tool execution indicator if tools were used
+        let fullText = text;
+        if (hasToolResults) {
+          const toolIndicator = toolResultCount === 1
+            ? "🛠️ **使用了 1 个工具**\n\n"
+            : `🛠️ **使用了 ${toolResultCount} 个工具**\n\n`;
+          fullText = toolIndicator + text;
+          // Reset after including in message
+          hasToolResults = false;
+          toolResultCount = 0;
+        }
+
+        if (!fullText.trim()) {
+          params.runtime.log?.(`popo-native deliver: empty text, skipping`);
+          return;
+        }
+
+        const chunks = core.channel.text.chunkTextWithMode(fullText, textChunkLimit, chunkMode);
+        params.runtime.log?.(`popo-native deliver: sending ${chunks.length} chunks to ${sessionId}`);
+
+        for (const chunk of chunks) {
+          // Native API only supports raw text mode (no rich_text variant)
+          await sendMessagePopoNative({
+            cfg,
+            to: sessionId,
+            text: chunk,
+          });
+        }
+      },
+      onError: (err, info) => {
+        params.runtime.error?.(`popo-native ${info.kind} reply failed: ${String(err)}`);
+        typingCallbacks.onIdle?.();
+      },
+      onIdle: typingCallbacks.onIdle,
+    });
+
+  return {
+    dispatcher,
+    replyOptions: {
+      ...replyOptions,
+      onModelSelected: prefixContext.onModelSelected,
+      // Track tool results as they are executed
+      onToolResult: (_payload: { text?: string; mediaUrls?: string[] }) => {
+        hasToolResults = true;
+        toolResultCount++;
+        params.runtime.log?.(`popo-native: tracked tool result #${toolResultCount}`);
+      },
+    },
+    markDispatchIdle,
+  };
+}

package/src/runtime.ts

@@ -0,0 +1,14 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+
+let runtime: PluginRuntime | null = null;
+
+export function setPopoNativeRuntime(next: PluginRuntime) {
+  runtime = next;
+}
+
+export function getPopoNativeRuntime(): PluginRuntime {
+  if (!runtime) {
+    throw new Error("POPO Native runtime not initialized");
+  }
+  return runtime;
+}