@buz-extensions/buz 1.0.0-beta.1

package/README.md

@@ -0,0 +1,58 @@
+# @buz-extensions/buz
+
+buz channel plugin for OpenClaw. This plugin connects OpenClaw to buz through a gRPC bidirectional stream.
+
+## Install
+
+```bash
+openclaw plugins install @buz-extensions/buz
+```
+
+## Configuration
+
+Configure the `buz` channel in your OpenClaw config.
+
+### Single account
+
+```yaml
+channels:
+  buz:
+    enabled: true
+    accounts:
+      default:
+        enabled: true
+        serverAddress: grpc.buz.ai:443
+        secretKey: your-secret-key
+```
+
+### Multiple accounts
+
+```yaml
+channels:
+  buz:
+    enabled: true
+    accounts:
+      accountA:
+        enabled: true
+        serverAddress: grpc.buz.ai:443
+        secretKey: secret-key-a
+      accountB:
+        enabled: true
+        serverAddress: grpc.buz.ai:443
+        secretKey: secret-key-b
+```
+
+## Features
+
+- buz channel registration
+- setup wizard support
+- inbound message dispatch
+- outbound text sending
+- account-based runtime management
+- gRPC reconnect and heartbeat
+
+## Notes
+
+- Channel id: `buz`
+- Requires OpenClaw runtime with plugin support
+- The package includes `openclaw.plugin.json` for native plugin validation

package/index.ts

@@ -0,0 +1,199 @@
+import type { ChannelPlugin, OpenClawPluginApi } from "openclaw/plugin-sdk/line";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk/line";
+import { buildChannelConfigSchema } from "openclaw/plugin-sdk/line";
+import { z } from "zod";
+
+const BuzAccountSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    serverAddress: z.string().optional(),
+    secretKey: z.string().optional(),
+  })
+  .partial();
+
+const BuzConfigSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    serverAddress: z.string().optional(),
+    secretKey: z.string().optional(),
+    accounts: z.record(z.string(), BuzAccountSchema.optional()).optional(),
+  })
+  .partial();
+
+export const buzChannelPlugin = {
+  id: "buz",
+  meta: {
+    id: "buz",
+    label: "buz",
+    selectionLabel: "buz (gRPC)",
+    docsPath: "/channels/buz",
+    blurb: "Connect OpenClaw to buz via gRPC bidirectional stream.",
+  },
+  capabilities: {
+    chatTypes: ["direct", "group"],
+    reactions: false,
+    threads: true,
+    media: false,
+  },
+  configSchema: buildChannelConfigSchema(BuzConfigSchema),
+  config: {
+    listAccountIds: (cfg: any) => {
+      const accounts = cfg?.channels?.["buz"]?.accounts || {};
+      const ids = Object.keys(accounts);
+      return ids.length > 0 ? ids : ["default"];
+    },
+    resolveAccount: (cfg: any, accountId?: string | null) => {
+      const id = accountId || "default";
+      const channelConfig = cfg?.channels?.["buz"] ?? {};
+
+      const topLevelDefault =
+        id === "default"
+          ? {
+              enabled: channelConfig.enabled,
+              serverAddress: channelConfig.serverAddress,
+              secretKey: channelConfig.secretKey,
+            }
+          : undefined;
+
+      const accountConfig = channelConfig?.accounts?.[id] ?? topLevelDefault ?? {};
+      const configured = Boolean(accountConfig.serverAddress && accountConfig.secretKey);
+
+      return {
+        accountId: id,
+        name: `buz (${id})`,
+        enabled: accountConfig.enabled !== false,
+        serverAddress: accountConfig.serverAddress,
+        secretKey: accountConfig.secretKey,
+        configured,
+        config: accountConfig,
+      };
+    },
+    isConfigured: (account: any) => Boolean(account.configured),
+    describeAccount: (account: any) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: Boolean(account.configured),
+    }),
+  },
+  messaging: {
+    normalizeTarget: (target: string) => target,
+    targetResolver: {
+      looksLikeId: (_id: string) => true,
+      hint: "<targetId>",
+    },
+    resolveSessionTarget: ({ id }: any) => id,
+  },
+  setupWizard: {
+    steps: [
+      {
+        id: "serverAddress",
+        type: "text",
+        label: "Server Address",
+        placeholder: "e.g. grpc.buz.ai:443",
+      },
+      {
+        id: "secretKey",
+        type: "password",
+        label: "Secret Key",
+        placeholder: "Enter your IM Secret Key",
+      },
+    ],
+  },
+  setup: {
+    validateInput: async (params: any) => {
+      const { setupAdapter } = await import("./src/setup.js");
+      return setupAdapter.validateInput(params);
+    },
+    applyAccountConfig: async (params: any) => {
+      const { setupAdapter } = await import("./src/setup.js");
+      const result = await setupAdapter.applyAccountConfig(params);
+      return result;
+    },
+  },
+  outbound: {
+    deliveryMode: "direct",
+    chunker: null,
+    textChunkLimit: 4000,
+    sendText: async ({ to, text, accountId, replyToId, threadId, cfg }: any) => {
+      const { sendText } = await import("./src/outbound.js");
+      return await sendText({ to, text, accountId, replyToId, threadId, cfg });
+    },
+    sendMedia: async ({ to }: any) => {
+      return { messageId: "media-unsupported", chatId: to };
+    },
+  },
+  status: {
+    defaultRuntime: {
+      accountId: "default",
+      running: false,
+      connected: false,
+      lastStartAt: null,
+      lastStopAt: null,
+      lastError: null,
+      lastInboundAt: null,
+      lastOutboundAt: null,
+    },
+    buildChannelSummary: ({ snapshot }: any) => {
+      if (!snapshot?.configured)
+        return { text: "Not configured", kind: "muted", configured: false };
+      if (snapshot?.connected) return { text: "Connected", kind: "healthy", configured: true };
+      if (snapshot?.running) return { text: "Starting", kind: "warning", configured: true };
+      return { text: "Configured", kind: "warning", configured: true };
+    },
+    buildAccountSnapshot: ({ account, runtime }: any) => {
+      return {
+        accountId: account.accountId,
+        name: account.name,
+        enabled: account.enabled,
+        configured: Boolean(account.configured),
+        running: runtime?.running ?? false,
+        connected: runtime?.connected ?? false,
+        lastStartAt: runtime?.lastStartAt ?? null,
+        lastStopAt: runtime?.lastStopAt ?? null,
+        mode: "grpc",
+        ...(runtime?.lastError ? { lastError: runtime.lastError } : {}),
+        ...(runtime?.lastInboundAt ? { lastInboundAt: runtime.lastInboundAt } : {}),
+        ...(runtime?.lastOutboundAt ? { lastOutboundAt: runtime.lastOutboundAt } : {}),
+      };
+    },
+  },
+  gateway: {
+    startAccount: async (ctx: any) => {
+      const account = ctx.account;
+      const serverAddress = account.serverAddress;
+      const secretKey = account.secretKey;
+
+      if (!serverAddress || !secretKey) {
+        throw new Error("Missing serverAddress or secretKey for buz");
+      }
+
+      ctx.log?.info(`[${account.accountId}] starting buz gRPC provider to ${serverAddress}`);
+
+      const { startGateway } = await import("./src/gateway.js");
+      const result = await startGateway(ctx, serverAddress, secretKey);
+      return result;
+    },
+    stopAccount: async (ctx: any) => {
+      const { stopGateway } = await import("./src/gateway.js");
+      return stopGateway(ctx);
+    },
+  },
+} as any;
+
+export const setBuzRuntime = (_runtime: any) => {
+  // buz doesn't need special runtime setup yet
+};
+
+const plugin = {
+  id: "buz",
+  name: "buz Plugin",
+  description: "Connects OpenClaw to buz",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: OpenClawPluginApi) {
+    setBuzRuntime(api.runtime);
+    api.registerChannel({ plugin: buzChannelPlugin as ChannelPlugin });
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,40 @@
+{
+  "id": "buz",
+  "channels": ["buz"],
+  "name": "buz Plugin",
+  "description": "Connects OpenClaw to buz",
+  "enabledByDefault": true,
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "enabled": {
+        "type": "boolean"
+      },
+      "serverAddress": {
+        "type": "string"
+      },
+      "secretKey": {
+        "type": "string"
+      },
+      "accounts": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "enabled": {
+              "type": "boolean"
+            },
+            "serverAddress": {
+              "type": "string"
+            },
+            "secretKey": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@buz-extensions/buz",
+  "version": "1.0.0-beta.1",
+  "description": "OpenClaw buz channel plugin",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "openclaw-channel",
+    "buz",
+    "grpc"
+  ],
+  "files": [
+    "index.ts",
+    "setup-entry.ts",
+    "openclaw.plugin.json",
+    "src",
+    "proto",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./index.ts",
+    "./setup-entry": "./setup-entry.ts",
+    "./openclaw.plugin.json": "./openclaw.plugin.json"
+  },
+  "dependencies": {
+    "@grpc/grpc-js": "^1.10.0",
+    "@grpc/proto-loader": "^0.7.10",
+    "zod": "^3.25.76"
+  },
+  "peerDependencies": {
+    "openclaw": "*"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "setupEntry": "./setup-entry.ts",
+    "channel": {
+      "id": "buz",
+      "label": "buz",
+      "selectionLabel": "buz (gRPC)",
+      "docsPath": "/channels/buz"
+    },
+    "install": {
+      "npmSpec": "@buz-extensions/buz",
+      "localPath": "extensions/buz_openclaw_channel",
+      "defaultChoice": "npm"
+    },
+    "bundle": {
+      "stageRuntimeDependencies": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/proto/buz.proto

@@ -0,0 +1,70 @@
+syntax = "proto3";
+package buz.dc.ai.bridge;
+
+// 核心桥接服务
+service OpenClawBridgeService {
+  // 双向流式通道
+  rpc ConnectStream(stream ClientToBridgeMessage) returns (stream BridgeToClientMessage);
+}
+
+// OpenClaw (Client) 发送给 buz (Server) 的消息
+message ClientToBridgeMessage {
+  oneof payload {
+    AuthRequest auth_req = 1;            // 1. 鉴权请求 (建连后第一条必须是这个)
+    OutboundMessage outbound_msg = 2;    // 2. OpenClaw 发出的回复消息
+    HeartbeatPing ping = 3;              // 3. 客户端心跳
+    ActionStatusReport action_status = 4;// 4. [可选] 已读回执/正在输入状态
+  }
+}
+
+// buz (Server) 发送给 OpenClaw (Client) 的消息
+message BridgeToClientMessage {
+  oneof payload {
+    AuthResponse auth_res = 1;           // 1. 鉴权结果
+    InboundMessage inbound_msg = 2;      // 2. IM 传递给 OpenClaw 的新消息
+    HeartbeatPong pong = 3;              // 3. 服务端心跳响应
+  }
+}
+
+// --- 详细子结构 ---
+
+message AuthRequest {
+  string secret_key = 1;     // 用户在 OpenClaw 输入的接入凭证
+  string openclaw_id = 2;    // [可选] 客户端唯一标识
+}
+
+message AuthResponse {
+  bool success = 1;
+  string error_message = 2;
+  string account_id = 3;     // 绑定成功的 IM 账户 ID
+}
+
+message InboundMessage {
+  string message_id = 1;     // IM 侧的全局消息 ID
+  string sender_id = 2;      // 发送者 ID
+  string sender_name = 3;    // 发送者昵称
+  string chat_type = 4;      // 枚举: "direct"(单聊), "group"(群聊)
+  string group_id = 5;       // 如果是群聊，群 ID
+  string content_text = 6;   // 文本内容
+  // 可扩展媒体字段 (media_url 等)
+}
+
+message OutboundMessage {
+  string reply_to_id = 1;    // 回复的目标消息 ID (Thread 追踪)
+  string target_id = 2;      // 接收方 ID (用户 ID 或 群组 ID)
+  string chat_type = 3;      // "direct" 或 "group"
+  string content_text = 4;   // AI 生成的回复文本
+  // 可扩展媒体字段
+}
+
+message HeartbeatPing {
+  int64 timestamp = 1;
+}
+
+message HeartbeatPong {
+  int64 timestamp = 1;
+}
+
+message ActionStatusReport {
+  string status = 1;
+}

package/setup-entry.ts

@@ -0,0 +1,5 @@
+import plugin, { buzChannelPlugin, setBuzRuntime } from "./index.js";
+
+export { buzChannelPlugin, setBuzRuntime } from "./index.js";
+
+export default plugin;

package/src/gateway.ts

@@ -0,0 +1,320 @@
+import { resolve } from "path";
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import * as grpc from "@grpc/grpc-js";
+import * as protoLoader from "@grpc/proto-loader";
+import { handleInboundMessage } from "./inbound.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+export const activeStreams = new Map<string, grpc.ClientDuplexStream<any, any>>();
+export const activeClients = new Map<string, any>();
+
+function setStatus(ctx: any, patch: Record<string, unknown>) {
+  console.log(`[buz gateway] setStatus called:`, patch);
+  ctx.setStatus?.({
+    accountId: ctx.account?.accountId || "default",
+    ...patch,
+  });
+}
+
+export async function startGateway(ctx: any, serverAddress: string, secretKey: string) {
+  const PROTO_PATH = resolve(__dirname, "../proto/buz.proto");
+
+  let packageDefinition;
+  try {
+    packageDefinition = protoLoader.loadSync(PROTO_PATH, {
+      keepCase: true,
+      longs: String,
+      enums: String,
+      defaults: true,
+      oneofs: true,
+    });
+    console.log("[buz gateway] proto loaded successfully");
+  } catch (err: any) {
+    console.error("[buz gateway] failed to load proto:", err.message);
+    throw err;
+  }
+
+  const protoDescriptor = grpc.loadPackageDefinition(packageDefinition) as any;
+  const bridgePackage = protoDescriptor.buz.dc.ai.bridge;
+  console.log("[buz gateway] bridgePackage exists:", !!bridgePackage);
+  console.log(
+    "[buz gateway] OpenClawBridgeService exists:",
+    !!bridgePackage?.OpenClawBridgeService,
+  );
+
+  const useSsl = serverAddress.includes("443") || serverAddress.startsWith("https");
+  console.log("[buz gateway] using SSL:", useSsl);
+
+  const credentials = useSsl ? grpc.credentials.createSsl() : grpc.credentials.createInsecure();
+
+  const cleanAddress = serverAddress.replace(/^https?:\/\//, "");
+  console.log("[buz gateway] connecting to:", cleanAddress);
+
+  let client;
+  try {
+    client = new bridgePackage.OpenClawBridgeService(cleanAddress, credentials);
+    console.log("[buz gateway] gRPC client created");
+  } catch (err: any) {
+    console.error("[buz gateway] failed to create client:", err.message);
+    throw err;
+  }
+
+  const accountId = ctx.account.accountId;
+  console.log("[buz gateway] accountId:", accountId);
+  activeClients.set(accountId, client);
+  console.log("[buz gateway] client stored in activeClients, total:", activeClients.size);
+
+  let stream: grpc.ClientDuplexStream<any, any> | null = null;
+  let reconnectAttempts = 0;
+  let everConnected = false;
+  let isActive = true;
+  let pingInterval: NodeJS.Timeout | null = null;
+  let reconnectTimer: NodeJS.Timeout | null = null;
+
+  const cleanupStream = () => {
+    console.log("[buz gateway] cleanupStream called");
+    if (pingInterval) {
+      clearInterval(pingInterval);
+      pingInterval = null;
+    }
+    if (stream) {
+      activeStreams.delete(accountId);
+      stream.removeAllListeners();
+      stream = null;
+    }
+  };
+
+  const scheduleReconnect = (reason?: string) => {
+    console.log(`[buz gateway] scheduleReconnect called, reason: ${reason || "none"}`);
+    cleanupStream();
+    // Keep running: true during reconnect attempts
+    setStatus(ctx, {
+      connected: false,
+      running: true, // Still trying to run
+      ...(reason ? { lastError: reason } : {}),
+    });
+
+    if (!isActive || ctx.abortSignal?.aborted) {
+      console.log("[buz gateway] aborting reconnect (isActive=false or aborted)");
+      return;
+    }
+
+    const delay = Math.min(1000 * Math.pow(2, reconnectAttempts), 30000);
+    reconnectAttempts += 1;
+    console.log(`[buz gateway] reconnecting in ${delay}ms (attempt ${reconnectAttempts})`);
+    ctx.log?.warn?.(
+      `[${accountId}] buz gRPC disconnected${reason ? `: ${reason}` : ""}; reconnecting in ${delay}ms`,
+    );
+    reconnectTimer = setTimeout(() => {
+      reconnectTimer = null;
+      connect();
+    }, delay);
+  };
+
+  const connect = () => {
+    console.log("[buz gateway] connect() called");
+    if (!isActive || ctx.abortSignal?.aborted) {
+      console.log("[buz gateway] aborting connect (isActive=false or aborted)");
+      return;
+    }
+
+    cleanupStream();
+    setStatus(ctx, {
+      connected: false,
+      running: true, // Mark as running while connecting
+      lastError: everConnected ? null : "connecting",
+    });
+
+    // Create metadata with authorization header
+    const metadata = new grpc.Metadata();
+    metadata.add("authorization", `Bearer ${secretKey}`);
+    metadata.add("x-openclaw-id", accountId);
+    console.log("[buz gateway] metadata created with authorization header");
+
+    try {
+      stream = client.ConnectStream(metadata);
+      console.log("[buz gateway] stream created:", !!stream);
+    } catch (err: any) {
+      console.error("[buz gateway] failed to create gRPC stream:", err?.message || String(err));
+      ctx.log?.error?.(
+        `[${accountId}] failed to create gRPC stream: ${err?.message || String(err)}`,
+      );
+      scheduleReconnect(err?.message || String(err));
+      return;
+    }
+
+    if (!stream) {
+      console.error("[buz gateway] stream is null after creation");
+      ctx.log?.error?.(`[${accountId}] failed to create gRPC stream: stream is null`);
+      scheduleReconnect("stream is null");
+      return;
+    }
+
+    activeStreams.set(accountId, stream);
+    console.log("[buz gateway] stream stored, total active streams:", activeStreams.size);
+
+    // Send auth request via message body (for backward compatibility)
+    const authRequest = {
+      auth_req: {
+        secret_key: secretKey,
+        openclaw_id: accountId,
+      },
+    };
+
+    try {
+      stream.write(authRequest);
+    } catch (err: any) {
+      console.error("[buz gateway] failed to send auth request:", err?.message);
+      // Don't schedule reconnect here, let the stream error handler deal with it
+    }
+
+    stream.on("data", async (msg: any) => {
+      console.log("[buz gateway] stream received data:", Object.keys(msg));
+
+      if (msg.auth_res) {
+        console.log("[buz gateway] received auth_res:", msg.auth_res);
+        if (msg.auth_res.success) {
+          everConnected = true;
+          reconnectAttempts = 0;
+          // IMPORTANT: Must include running: true
+          setStatus(ctx, {
+            running: true,
+            connected: true,
+            lastError: null,
+            lastStartAt: Date.now(),
+          });
+          ctx.log?.info?.(`[${accountId}] buz gRPC authenticated successfully.`);
+          console.log("[buz gateway] authentication successful");
+
+          if (pingInterval) clearInterval(pingInterval);
+          pingInterval = setInterval(() => {
+            console.log("[buz gateway] sending heartbeat");
+            if (stream) {
+              try {
+                stream.write({
+                  ping: { timestamp: Date.now() },
+                });
+              } catch (err: any) {
+                ctx.log?.warn?.(
+                  `[${accountId}] failed to send buz heartbeat: ${err?.message || String(err)}`,
+                );
+              }
+            }
+          }, 30000);
+          console.log("[buz gateway] heartbeat interval set (30s)");
+        } else {
+          const reason = `Auth failed: ${msg.auth_res.error_message || "unknown error"}`;
+          console.error("[buz gateway] authentication failed:", reason);
+          ctx.log?.error?.(`[${accountId}] ${reason}`);
+          scheduleReconnect(reason);
+        }
+        return;
+      }
+
+      if (msg.inbound_msg) {
+        console.log("[buz gateway] received inbound message");
+        // Update lastInboundAt when receiving messages
+        setStatus(ctx, {
+          lastInboundAt: Date.now(),
+          running: true,
+          connected: true,
+        });
+        await handleInboundMessage(ctx, msg.inbound_msg);
+        return;
+      }
+
+      if (msg.pong) {
+        return;
+      }
+
+      console.log("[buz gateway] received unknown message type:", Object.keys(msg));
+    });
+
+    stream.on("end", () => {
+      console.log("[buz gateway] stream ended");
+      scheduleReconnect("stream ended");
+    });
+
+    stream.on("error", (err: any) => {
+      const reason = err?.message || String(err);
+      console.error("[buz gateway] stream error:", reason);
+      ctx.log?.error?.(`[${accountId}] gRPC stream error: ${reason}`);
+      scheduleReconnect(reason);
+    });
+
+    console.log("[buz gateway] stream event handlers registered");
+  };
+
+  console.log("[buz gateway] initializing connection...");
+  setStatus(ctx, {
+    running: true, // Mark as running from the start
+    connected: false,
+    lastError: null,
+    lastStartAt: Date.now(),
+  });
+  connect();
+  console.log("[buz gateway] connect() invoked");
+
+  ctx.abortSignal?.addEventListener("abort", () => {
+    console.log("[buz gateway] abort signal received");
+    isActive = false;
+    if (reconnectTimer) {
+      clearTimeout(reconnectTimer);
+      reconnectTimer = null;
+    }
+    cleanupStream();
+    const activeStream = activeStreams.get(accountId);
+    if (activeStream) {
+      activeStream.cancel();
+      activeStreams.delete(accountId);
+    }
+    const activeClient = activeClients.get(accountId);
+    if (activeClient) {
+      activeClient.close();
+      activeClients.delete(accountId);
+    }
+    setStatus(ctx, {
+      connected: false,
+      running: false,
+      lastStopAt: Date.now(),
+    });
+  });
+
+  return {
+    running: true,
+    connected: false,
+    lastStartAt: Date.now(),
+    lastError: null,
+  };
+}
+
+export async function stopGateway(ctx: any) {
+  console.log("[buz gateway] stopGateway called");
+  const accountId = ctx.account?.accountId || "default";
+  console.log("[buz gateway] stopping account:", accountId);
+
+  const stream = activeStreams.get(accountId);
+  if (stream) {
+    console.log("[buz gateway] cancelling stream");
+    stream.cancel();
+    activeStreams.delete(accountId);
+  }
+
+  const client = activeClients.get(accountId);
+  if (client) {
+    console.log("[buz gateway] closing client");
+    client.close();
+    activeClients.delete(accountId);
+  }
+
+  ctx.setStatus?.({
+    accountId,
+    connected: false,
+    running: false,
+    lastStopAt: Date.now(),
+  });
+  console.log("[buz gateway] stopGateway complete");
+}

package/src/inbound.ts

@@ -0,0 +1,151 @@
+import { recordInboundSession } from "openclaw/plugin-sdk";
+import { sendText } from "./outbound.js";
+
+function resolveDefaultAgentIdCompat(cfg: any): string {
+  const configured = cfg?.defaultAgentId ?? cfg?.agents?.default ?? cfg?.agent?.default;
+  if (typeof configured === "string" && configured.trim()) {
+    return configured.trim();
+  }
+  const agents = Array.isArray(cfg?.agents) ? cfg.agents : undefined;
+  const firstAgentId = agents?.find((entry: any) => typeof entry?.id === "string" && entry.id.trim())?.id;
+  return firstAgentId || "default";
+}
+
+function resolveDispatchReplyWithBufferedBlockDispatcher(ctx: any):
+  | ((params: any) => Promise<any>)
+  | null {
+  return (
+    ctx?.runtime?.channel?.reply?.dispatchReplyWithBufferedBlockDispatcher ??
+    ctx?.core?.channel?.reply?.dispatchReplyWithBufferedBlockDispatcher ??
+    null
+  );
+}
+
+export async function handleInboundMessage(ctx: any, inboundMsg: any) {
+  console.log("[buz inbound] =========================================");
+  console.log("[buz inbound] handleInboundMessage called");
+  console.log("[buz inbound] inboundMsg keys:", Object.keys(inboundMsg || {}));
+  console.log("[buz inbound] inboundMsg:", JSON.stringify(inboundMsg, null, 2));
+
+  const accountId = ctx.account.accountId;
+  const cfg = ctx.cfg;
+  const agentId = resolveDefaultAgentIdCompat(cfg);
+
+  console.log("[buz inbound] accountId:", accountId);
+  console.log("[buz inbound] agentId:", agentId);
+
+  const fromTarget =
+    inboundMsg.chat_type === "group"
+      ? `buz:group:${inboundMsg.group_id}:${inboundMsg.sender_id}`
+      : `buz:${inboundMsg.sender_id}`;
+
+  const toTarget =
+    inboundMsg.chat_type === "group"
+      ? `buz:group:${inboundMsg.group_id}`
+      : `buz:${inboundMsg.sender_id}`;
+
+  const conversationId =
+    inboundMsg.chat_type === "group" ? inboundMsg.group_id : inboundMsg.sender_id;
+
+  console.log("[buz inbound] fromTarget:", fromTarget);
+  console.log("[buz inbound] toTarget:", toTarget);
+  console.log("[buz inbound] conversationId:", conversationId);
+
+  const ctxPayload = {
+    MessageSid: inboundMsg.message_id || Date.now().toString(),
+    MessageSids: [inboundMsg.message_id || Date.now().toString()],
+    SessionKey: `buz:${accountId}:${conversationId}`,
+    ConversationId: conversationId,
+    From: fromTarget,
+    To: toTarget,
+    Body: inboundMsg.content_text || "",
+    BodyForAgent: inboundMsg.content_text || "",
+    BodyForCommands: inboundMsg.content_text || "",
+    Channel: "buz",
+    SenderName: inboundMsg.sender_name || inboundMsg.sender_id,
+  };
+
+  console.log("[buz inbound] ctxPayload:", JSON.stringify(ctxPayload, null, 2));
+
+  const storePath = cfg?.session?.storePath || ".openclaw/sessions";
+  console.log("[buz inbound] recording inbound session, storePath:", storePath);
+  console.log("[buz inbound] sessionKey:", ctxPayload.SessionKey);
+
+  try {
+    await recordInboundSession({
+      storePath,
+      sessionKey: ctxPayload.SessionKey,
+      ctx: ctxPayload,
+      updateLastRoute: {
+        sessionKey: ctxPayload.SessionKey,
+        channel: "buz",
+        to: toTarget,
+        accountId,
+      },
+      onRecordError: (err) => {
+        console.error("[buz inbound] failed to record session:", err);
+      },
+    });
+    console.log("[buz inbound] session recorded successfully");
+  } catch (err: any) {
+    console.error("[buz inbound] error recording session:", err.message);
+  }
+
+  const dispatchReplyWithBufferedBlockDispatcher =
+    resolveDispatchReplyWithBufferedBlockDispatcher(ctx);
+  if (!dispatchReplyWithBufferedBlockDispatcher) {
+    const error = new Error(
+      "OpenClaw reply runtime is unavailable on plugin context; missing channel reply dispatcher",
+    );
+    console.error("[buz inbound] failed to dispatch:", error.message);
+    ctx.log?.error?.(`[${accountId}] Failed to dispatch inbound message: ${error.message}`);
+    throw error;
+  }
+
+  try {
+    console.log("[buz inbound] dispatching inbound message...");
+    await dispatchReplyWithBufferedBlockDispatcher({
+      ctx: ctxPayload as any,
+      cfg,
+      dispatcherOptions: {
+        cfg,
+        agentId,
+        channel: "buz",
+        accountId,
+        deliver: async (payload: any, info: any) => {
+          console.log(
+            "[buz inbound] deliver called:",
+            info?.kind,
+            "text:",
+            payload?.text?.substring?.(0, 50),
+          );
+          if (!payload?.text) {
+            return;
+          }
+          await sendText({
+            to: toTarget,
+            text: payload.text,
+            accountId,
+            replyToId: inboundMsg.message_id,
+          });
+          console.log("[buz inbound] reply sent successfully via gRPC");
+        },
+        onError: (err: any, info: any) => {
+          console.error(`[buz inbound] ${info?.kind || "unknown"} reply failed:`, err);
+        },
+      },
+      replyOptions: {
+        disableBlockStreaming: true,
+      },
+    });
+    console.log("[buz inbound] message dispatched successfully");
+    ctx.log?.info?.(
+      `[${accountId}] Successfully dispatched inbound message from ${inboundMsg.sender_id}`,
+    );
+  } catch (err: any) {
+    console.error("[buz inbound] failed to dispatch:", err.message);
+    ctx.log?.error?.(`[${accountId}] Failed to dispatch inbound message: ${err.message}`);
+    throw err;
+  }
+  console.log("[buz inbound] =========================================");
+}

package/src/outbound.ts

@@ -0,0 +1,74 @@
+import { activeStreams } from "./gateway.js";
+
+export async function sendText(params: any) {
+  const { to, text, accountId, replyToId } = params;
+
+  console.log("[buz outbound] =========================================");
+  console.log("[buz outbound] sendText called");
+  console.log("[buz outbound] to:", to);
+  console.log("[buz outbound] text preview:", text?.substring(0, 100));
+  console.log("[buz outbound] text length:", text?.length);
+  console.log("[buz outbound] accountId:", accountId);
+  console.log("[buz outbound] replyToId:", replyToId);
+
+  const targetAccountId = accountId || "default";
+  console.log("[buz outbound] targetAccountId:", targetAccountId);
+
+  const stream = activeStreams.get(targetAccountId);
+  console.log("[buz outbound] activeStreams size:", activeStreams.size);
+  console.log("[buz outbound] stream found:", !!stream);
+
+  if (!stream) {
+    console.error("[buz outbound] ERROR: No active gRPC stream for account", targetAccountId);
+    console.log("[buz outbound] activeStreams keys:", Array.from(activeStreams.keys()));
+    throw new Error(`[buz] No active gRPC stream for account ${targetAccountId}`);
+  }
+
+  // to format might be: "buz:group:GROUP_ID" or "buz:USER_ID"
+  // based on inbound parsing or explicit routing
+  let chatType = "direct";
+  let targetId = to;
+
+  console.log("[buz outbound] parsing target:", to);
+
+  if (to.startsWith("buz:")) {
+    targetId = to.substring("buz:".length);
+    console.log("[buz outbound] removed 'buz:' prefix, targetId:", targetId);
+  }
+
+  if (targetId.startsWith("group:")) {
+    chatType = "group";
+    targetId = targetId.substring("group:".length);
+    console.log("[buz outbound] detected group chat, targetId:", targetId);
+    // if targetId has a suffix like :sender_id, remove it for group target
+    if (targetId.includes(":")) {
+      targetId = targetId.split(":")[0];
+      console.log("[buz outbound] removed sender suffix, final targetId:", targetId);
+    }
+  } else if (targetId.startsWith("user:")) {
+    targetId = targetId.substring("user:".length);
+    console.log("[buz outbound] removed 'user:' prefix, targetId:", targetId);
+  }
+
+  const outboundMsg = {
+    outbound_msg: {
+      reply_to_id: replyToId || "",
+      target_id: targetId,
+      chat_type: chatType,
+      content_text: text,
+    },
+  };
+
+  console.log("[buz outbound] outboundMsg:", JSON.stringify(outboundMsg, null, 2));
+
+  try {
+    stream.write(outboundMsg);
+    console.log("[buz outbound] gRPC stream write successful");
+  } catch (err: any) {
+    console.error("[buz outbound] ERROR writing to stream:", err.message);
+    throw err;
+  }
+
+  const result = { messageId: `msg-${Date.now()}`, chatId: to };
+  return result;
+}

package/src/setup.ts

@@ -0,0 +1,99 @@
+export const setupAdapter = {
+  validateInput: async (params: any) => {
+    console.log("[buz setup] validateInput called with params:", {
+      hasValues: !!params.values,
+      hasInput: !!params.input,
+      accountId: params.accountId,
+      keys: Object.keys(params.values || params.input || {}),
+    });
+
+    const input = params.values || params.input || {};
+    const { serverAddress, secretKey } = input;
+
+    console.log("[buz setup] extracted values:", {
+      hasServerAddress: !!serverAddress,
+      hasSecretKey: !!secretKey,
+      serverAddressLength: serverAddress?.length,
+      secretKeyLength: secretKey?.length,
+    });
+
+    if (!serverAddress) return { ok: false, error: "Server Address is required" };
+    if (!secretKey) return { ok: false, error: "Secret Key is required" };
+    return { ok: true, values: input };
+  },
+
+  applyAccountConfig: async (params: any) => {
+    const { cfg, accountId } = params;
+    // OpenClaw passes "input" instead of "values"
+    const input = params.input || params.values || {};
+    const resolvedAccountId = accountId || "default";
+
+    console.log("[buz setup] applyAccountConfig called:", {
+      accountId,
+      resolvedAccountId,
+      hasCfg: !!cfg,
+      hasInput: !!input,
+      inputKeys: Object.keys(input),
+      hasServerAddress: !!input.serverAddress,
+      hasSecretKey: !!input.secretKey,
+      existingChannelsKeys: Object.keys(cfg?.channels || {}),
+    });
+
+    // Deep clone to avoid mutations
+    const newCfg = JSON.parse(JSON.stringify(cfg || {}));
+
+    if (!newCfg.channels) {
+      newCfg.channels = {};
+      console.log("[buz setup] created new channels object");
+    }
+
+    const existingChannelCfg = newCfg.channels["buz"] || {};
+    console.log("[buz setup] existing channel config:", {
+      hasExisting: !!newCfg.channels["buz"],
+      existingKeys: Object.keys(existingChannelCfg),
+      existingAccountsKeys: Object.keys(existingChannelCfg.accounts || {}),
+    });
+
+    // Ensure the buz channel config exists with proper structure
+    newCfg.channels["buz"] = {
+      ...existingChannelCfg,
+      enabled: true,
+      accounts: {
+        ...(existingChannelCfg.accounts || {}),
+      },
+    };
+
+    // Set the account config
+    newCfg.channels["buz"].accounts[resolvedAccountId] = {
+      ...(newCfg.channels["buz"].accounts[resolvedAccountId] || {}),
+      serverAddress: input.serverAddress,
+      secretKey: input.secretKey,
+      enabled: true,
+    };
+
+    console.log("[buz setup] account config set:", {
+      accountId: resolvedAccountId,
+      hasServerAddress: !!newCfg.channels["buz"].accounts[resolvedAccountId].serverAddress,
+      hasSecretKey: !!newCfg.channels["buz"].accounts[resolvedAccountId].secretKey,
+      allAccountIds: Object.keys(newCfg.channels["buz"].accounts),
+    });
+
+    // Clean up top-level fields for default account (they should be in accounts.default)
+    if (resolvedAccountId === "default") {
+      delete newCfg.channels["buz"].serverAddress;
+      delete newCfg.channels["buz"].secretKey;
+      console.log("[buz setup] cleaned up top-level fields for default account");
+    }
+
+    console.log("[buz setup] final config structure:", {
+      channelsKeys: Object.keys(newCfg.channels),
+      buzKeys: Object.keys(newCfg.channels["buz"]),
+      buzEnabled: newCfg.channels["buz"].enabled,
+      accountIds: Object.keys(newCfg.channels["buz"].accounts),
+      defaultAccountKeys: Object.keys(newCfg.channels["buz"].accounts.default || {}),
+    });
+
+    // IMPORTANT: Return the entire cfg object, not just the channels part
+    return { cfg: newCfg, accountId: resolvedAccountId };
+  },
+};