@vibearound/plugin-channel-sdk 0.3.0 → 0.4.0

package/src/index.ts

@@ -1,94 +1,75 @@
 /**
  * @vibearound/plugin-channel-sdk
  *
- * Base classes and utilities for building VibeAround channel plugins.
+ * SDK for building VibeAround channel plugins.
  *
  * ## Quick start
  *
  * ```ts
  * import {
- *   connectToHost,
+ *   runChannelPlugin,
  *   BlockRenderer,
- *   normalizeExtMethod,
- *   type Agent,
- *   type SessionNotification,
+ *   type ChannelBot,
+ *   type BlockKind,
  * } from "@vibearound/plugin-channel-sdk";
  *
  * class MyRenderer extends BlockRenderer<string> {
- *   protected async sendBlock(channelId, kind, content) {
- *     const msg = await myPlatform.send(channelId, content);
- *     return msg.id;
- *   }
- *   protected async editBlock(channelId, ref, kind, content, sealed) {
- *     await myPlatform.edit(ref, content);
- *   }
+ *   protected async sendText(chatId: string, text: string) { ... }
+ *   protected async sendBlock(chatId: string, kind: BlockKind, content: string) { ... }
  * }
  *
- * let agent!: Agent;
- * const renderer = new MyRenderer();
+ * runChannelPlugin({
+ *   name: "vibearound-mybot",
+ *   version: "0.1.0",
+ *   requiredConfig: ["bot_token"],
+ *   createBot: ({ config, agent, log, cacheDir }) => new MyBot(...),
+ *   createRenderer: (bot, log, verbose) => new MyRenderer(bot, log, verbose),
+ * });
+ * ```
+ *
+ * ## Advanced / low-level usage
  *
- * const { meta, conn } = await connectToHost(
- *   { name: "vibearound-mybot", version: "0.1.0" },
- *   (a) => {
- *     agent = a;
- *     return {
- *       sessionUpdate: async (n) => renderer.onSessionUpdate(n),
- *       requestPermission: async (p) => ({
- *         outcome: { outcome: "selected", optionId: p.options![0].optionId },
- *       }),
- *       extNotification: async (method, params) => {
- *         switch (normalizeExtMethod(method)) {
- *           case "channel/system_text":
- *             await myPlatform.send(params.channelId as string, params.text as string);
- *             break;
- *         }
- *       },
- *     };
- *   },
- * );
+ * For plugins that need custom ACP lifecycle control (e.g. weixin-openclaw-bridge),
+ * import from the `advanced` subpath:
  *
- * const botToken = meta.config.bot_token as string;
- * // … start your platform bot …
- * await conn.closed;
+ * ```ts
+ * import { connectToHost } from "@vibearound/plugin-channel-sdk/advanced";
  * ```
  */
 
-// Connection helpers
-export { connectToHost, normalizeExtMethod, redirectConsoleToStderr } from "./connection.js";
-export type { PluginInfo, ConnectResult, AgentInfo } from "./connection.js";
+// ---------------------------------------------------------------------------
+// High-level API — what plugin developers use
+// ---------------------------------------------------------------------------
 
-// Error normalization
-export { extractErrorMessage } from "./errors.js";
+// Entry point
+export { runChannelPlugin } from "./plugin.js";
 
-// Plugin runner (absorbs the main.ts boilerplate)
-export { runChannelPlugin } from "./run-plugin.js";
+// Base class for stream rendering
+export { BlockRenderer } from "./renderer.js";
+
+// Interfaces the plugin implements
 export type {
   ChannelBot,
   ChannelPluginLogger,
-  ChannelStreamHandler,
   CreateBotContext,
   RunChannelPluginSpec,
   VerboseOptions,
-} from "./run-plugin.js";
-
-// Block renderer
-export { BlockRenderer } from "./renderer.js";
+} from "./plugin.js";
 
+// Types used in BlockRenderer overrides
+export type {
+  BlockKind,
+  CommandEntry,
+  VerboseConfig,
+  BlockRendererOptions,
+} from "./types.js";
 
-// Types (re-exports ACP SDK types + SDK-specific types)
+// ACP types the plugin needs for prompt content
 export type {
-  // ACP SDK
   Agent,
-  Client,
   ContentBlock,
   SessionNotification,
-  RequestPermissionRequest,
-  RequestPermissionResponse,
-  // SDK
-  BlockKind,
-  VerboseConfig,
-  BlockRendererOptions,
-  PluginCapabilities,
-  PluginManifest,
-  PluginInitMeta,
 } from "./types.js";
+
+// Error utility
+export { extractErrorMessage } from "./errors.js";

package/src/{run-plugin.ts → plugin.ts}

@@ -1,34 +1,23 @@
 /**
- * runChannelPlugin — shared main.ts boilerplate for every channel plugin.
+ * runChannelPlugin — the SDK entry point for every channel plugin.
  *
- * Each channel plugin used to have a ~120-line `main.ts` that was 85%
- * identical across Slack, Telegram, Discord, DingTalk, WeCom, etc:
- * connect to host, validate config keys, wire the standard sessionUpdate
- * and extNotification handlers, create the stream handler, start the bot,
- * wait for disconnect, stop. This helper absorbs that boilerplate so each
- * plugin's `main.ts` reduces to ~20 lines — a factory for the bot and a
- * factory for the stream handler.
+ * Handles the full ACP lifecycle: connect to host, validate config, create
+ * bot + renderer, start the bot, then await disconnect and stop. The plugin
+ * only implements platform-specific transport (sendText, sendBlock, editBlock).
  *
  * ## Usage
  *
  * ```ts
  * import { runChannelPlugin } from "@vibearound/plugin-channel-sdk";
- * import { SlackBot } from "./bot.js";
- * import { AgentStreamHandler } from "./agent-stream.js";
  *
  * runChannelPlugin({
  *   name: "vibearound-slack",
  *   version: "0.1.0",
  *   requiredConfig: ["bot_token", "app_token"],
  *   createBot: ({ config, agent, log, cacheDir }) =>
- *     new SlackBot(
- *       { bot_token: config.bot_token as string, app_token: config.app_token as string },
- *       agent,
- *       log,
- *       cacheDir,
- *     ),
- *   createStreamHandler: (bot, log, verbose) =>
- *     new AgentStreamHandler(bot, log, verbose),
+ *     new SlackBot({ ... }, agent, log, cacheDir),
+ *   createRenderer: (bot, log, verbose) =>
+ *     new SlackRenderer(bot, log, verbose),
  * });
  * ```
  */
@@ -37,8 +26,9 @@ import os from "node:os";
 import path from "node:path";
 import type { Agent } from "@agentclientprotocol/sdk";
 
-import { connectToHost, normalizeExtMethod } from "./connection.js";
+import { connectToHost, stripExtPrefix } from "./connection.js";
 import { extractErrorMessage } from "./errors.js";
+import { BlockRenderer } from "./renderer.js";
 import type {
   RequestPermissionRequest,
   RequestPermissionResponse,
@@ -51,16 +41,19 @@ import type {
 
 export type ChannelPluginLogger = (level: string, msg: string) => void;
 
-export interface ChannelStreamHandler {
-  onSessionUpdate(params: SessionNotification): void;
-  onSystemText(text: string): void;
-  onAgentReady(agent: string, version: string): void;
-  onSessionReady(sessionId: string): void;
-}
-
-export interface ChannelBot<THandler extends ChannelStreamHandler = ChannelStreamHandler> {
-  setStreamHandler(handler: THandler): void;
+/**
+ * The platform bot — handles IM connectivity and message transport.
+ *
+ * Plugins implement this interface on their bot class. The SDK calls these
+ * methods during the plugin lifecycle.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface ChannelBot<TRenderer extends BlockRenderer<any> = BlockRenderer<any>> {
+  /** Wire the renderer to receive streaming events. */
+  setStreamHandler(handler: TRenderer): void;
+  /** Connect to the IM platform and start receiving messages. */
   start(): Promise<void> | void;
+  /** Disconnect and clean up. */
   stop(): Promise<void> | void;
 }
 
@@ -77,8 +70,8 @@ export interface VerboseOptions {
 }
 
 export interface RunChannelPluginSpec<
-  TBot extends ChannelBot<THandler>,
-  THandler extends ChannelStreamHandler,
+  TBot extends ChannelBot<TRenderer>,
+  TRenderer extends BlockRenderer<any>,
 > {
   /** Plugin name reported during ACP initialize (e.g. "vibearound-slack"). */
   name: string;
@@ -87,30 +80,25 @@ export interface RunChannelPluginSpec<
   version: string;
 
   /**
-   * Config keys that MUST be present on `meta.config`. Plugin startup
-   * fails with a clear error if any are missing. Keep to primitives
-   * (strings/booleans); deeper validation belongs in the bot constructor.
+   * Config keys that MUST be present. Plugin fails fast if any are missing.
    */
   requiredConfig?: string[];
 
-  /** Factory: build the platform bot from host-supplied config + agent. */
+  /** Factory: build the platform bot. */
   createBot: (ctx: CreateBotContext) => TBot | Promise<TBot>;
 
   /**
-   * Factory: build the agent stream handler for this plugin. The handler
-   * is wired to the bot via `bot.setStreamHandler(handler)` before the
-   * bot is started.
+   * Factory: build the renderer (extends BlockRenderer).
+   * Only implements platform-specific sendText/sendBlock/editBlock.
    */
-  createStreamHandler: (
+  createRenderer: (
     bot: TBot,
     log: ChannelPluginLogger,
     verbose: VerboseOptions,
-  ) => THandler;
+  ) => TRenderer;
 
   /**
-   * Optional hook invoked after the bot has been constructed but before
-   * `start()` is called. Use this for one-off initialization that needs
-   * to log diagnostic info (e.g. Telegram's `probe()`).
+   * Optional hook invoked after bot constructed but before start().
    */
   afterCreate?: (bot: TBot, log: ChannelPluginLogger) => Promise<void> | void;
 }
@@ -120,18 +108,16 @@ export interface RunChannelPluginSpec<
 // ---------------------------------------------------------------------------
 
 /**
- * Run a channel plugin to completion.
- *
- * Performs the ACP initialize handshake, validates required config,
- * constructs the bot + stream handler, starts the bot, waits for the host
- * connection to close, then stops the bot and exits the process.
+ * Run a channel plugin.
  *
- * Never returns under normal operation — the process exits at the end.
+ * Handles the full ACP lifecycle: connect to host, validate config,
+ * construct bot + renderer, start the bot, then wait for the host
+ * to disconnect before stopping and exiting.
  */
 export async function runChannelPlugin<
-  TBot extends ChannelBot<THandler>,
-  THandler extends ChannelStreamHandler,
->(spec: RunChannelPluginSpec<TBot, THandler>): Promise<void> {
+  TBot extends ChannelBot<TRenderer>,
+  TRenderer extends BlockRenderer<any>,
+>(spec: RunChannelPluginSpec<TBot, TRenderer>): Promise<void> {
   const prefix = `[${spec.name.replace(/^vibearound-/, "")}-plugin]`;
   const log: ChannelPluginLogger = (level, msg) => {
     process.stderr.write(`${prefix}[${level}] ${msg}\n`);
@@ -146,21 +132,21 @@ export async function runChannelPlugin<
 }
 
 async function runInner<
-  TBot extends ChannelBot<THandler>,
-  THandler extends ChannelStreamHandler,
+  TBot extends ChannelBot<TRenderer>,
+  TRenderer extends BlockRenderer<any>,
 >(
-  spec: RunChannelPluginSpec<TBot, THandler>,
+  spec: RunChannelPluginSpec<TBot, TRenderer>,
   log: ChannelPluginLogger,
 ): Promise<void> {
   log("info", "initializing ACP connection...");
 
-  let streamHandler: THandler | null = null;
+  let renderer: TRenderer | null = null;
 
   const { agent, meta, agentInfo, conn } = await connectToHost(
     { name: spec.name, version: spec.version },
     () => ({
       async sessionUpdate(params: SessionNotification): Promise<void> {
-        streamHandler?.onSessionUpdate(params);
+        renderer?.onSessionUpdate(params);
       },
 
       async requestPermission(
@@ -177,23 +163,38 @@ async function runInner<
         method: string,
         params: Record<string, unknown>,
       ): Promise<void> {
-        switch (normalizeExtMethod(method)) {
-          case "channel/system_text": {
-            const text = params.text as string;
-            streamHandler?.onSystemText(text);
+        const chatId = typeof params.chatId === "string" ? params.chatId : undefined;
+        switch (stripExtPrefix(method)) {
+          case "va/system_text": {
+            const text = typeof params.text === "string" ? params.text : "";
+            if (chatId && renderer) {
+              renderer.onSystemText(chatId, text);
+            }
             break;
           }
-          case "channel/agent_ready": {
-            const agentName = params.agent as string;
-            const version = params.version as string;
+          case "va/agent_ready": {
+            const agentName = typeof params.agent === "string" ? params.agent : "unknown";
+            const version = typeof params.version === "string" ? params.version : "";
             log("info", `agent_ready: ${agentName} v${version}`);
-            streamHandler?.onAgentReady(agentName, version);
+            if (chatId && renderer) {
+              renderer.onAgentReady(chatId, agentName, version);
+            }
             break;
           }
-          case "channel/session_ready": {
-            const sessionId = params.sessionId as string;
+          case "va/session_ready": {
+            const sessionId = typeof params.sessionId === "string" ? params.sessionId : "";
             log("info", `session_ready: ${sessionId}`);
-            streamHandler?.onSessionReady(sessionId);
+            if (chatId && renderer) {
+              renderer.onSessionReady(chatId, sessionId);
+            }
+            break;
+          }
+          case "va/command_menu": {
+            const systemCommands = Array.isArray(params.systemCommands) ? params.systemCommands : [];
+            const agentCommands = Array.isArray(params.agentCommands) ? params.agentCommands : [];
+            if (chatId && renderer) {
+              renderer.onCommandMenu(chatId, systemCommands, agentCommands);
+            }
             break;
           }
           default:
@@ -205,9 +206,6 @@ async function runInner<
 
   const config = meta.config;
 
-  // Validate required config keys up front so a misconfigured plugin fails
-  // with a clear error instead of some downstream "undefined is not a
-  // string" crash in the bot constructor.
   for (const key of spec.requiredConfig ?? []) {
     if (config[key] === undefined || config[key] === null || config[key] === "") {
       throw new Error(`${key} is required in config`);
@@ -236,8 +234,8 @@ async function runInner<
     showToolUse: verboseRaw?.show_tool_use ?? false,
   };
 
-  streamHandler = spec.createStreamHandler(bot, log, verbose);
-  bot.setStreamHandler(streamHandler);
+  renderer = spec.createRenderer(bot, log, verbose);
+  bot.setStreamHandler(renderer);
 
   await bot.start();
   log("info", "plugin started");