@vibearound/plugin-channel-sdk 0.3.0 → 0.4.1

package/README.md

@@ -1,8 +1,8 @@
 # @vibearound/plugin-channel-sdk
 
-Base classes and utilities for building [VibeAround](https://github.com/anthropics/vibearound) channel plugins.
+SDK for building [VibeAround](https://github.com/jazzenchen/VibeAround) channel plugins.
 
-VibeAround channel plugins bridge messaging platforms (Telegram, Feishu, WeChat, etc.) to the VibeAround agent runtime via the [Agent Client Protocol (ACP)](https://github.com/anthropics/agent-client-protocol). This SDK extracts the shared patterns so you can focus on platform integration.
+Channel plugins bridge IM platforms (Feishu, Telegram, Slack, Discord, etc.) to the VibeAround agent runtime via [ACP](https://agentclientprotocol.com). This SDK handles the ACP lifecycle so you only implement platform-specific message transport.
 
 ## Install
 
@@ -10,141 +10,95 @@ VibeAround channel plugins bridge messaging platforms (Telegram, Feishu, WeChat,
 npm install @vibearound/plugin-channel-sdk
 ```
 
-## What it provides
-
-- **`connectToHost()`** — Sets up the ACP stdio connection, performs the initialize handshake, extracts plugin config from the host, and redirects console output to stderr.
-- **`BlockRenderer<TRef>`** — Abstract base class that handles block-based message rendering: accumulation of streaming deltas, kind-change detection, debounced flushing, edit throttling, and ordered delivery via a serialized Promise chain.
-- **`normalizeExtMethod()`** — Strips the `_` prefix the ACP SDK adds to extension method names.
-- **Types** — Re-exports common ACP SDK types (`Agent`, `Client`, `SessionNotification`, etc.) plus SDK-specific types (`BlockKind`, `VerboseConfig`, `PluginManifest`, etc.).
-
 ## Quick start
 
 ```ts
-import {
-  connectToHost,
-  BlockRenderer,
-  normalizeExtMethod,
-  type Agent,
-  type BlockKind,
-  type SessionNotification,
-} from "@vibearound/plugin-channel-sdk";
+import { runChannelPlugin, BlockRenderer, type BlockKind, type VerboseConfig } from "@vibearound/plugin-channel-sdk";
 
 // 1. Implement a renderer for your platform
 class MyRenderer extends BlockRenderer<string> {
-  protected async sendBlock(channelId: string, kind: BlockKind, content: string) {
-    const msg = await myPlatform.send(channelId, content);
-    return msg.id; // platform message reference for future edits
+  constructor(private bot: MyBot, log: Function, verbose?: Partial<VerboseConfig>) {
+    super({ streaming: true, flushIntervalMs: 500, minEditIntervalMs: 1000, verbose });
   }
 
-  // Optional — omit for platforms that don't support editing
-  protected async editBlock(channelId: string, ref: string, kind: BlockKind, content: string, sealed: boolean) {
-    await myPlatform.edit(ref, content);
+  protected async sendText(chatId: string, text: string) {
+    await this.bot.send(chatId, text);
+  }
+
+  protected async sendBlock(chatId: string, kind: BlockKind, content: string) {
+    const msg = await this.bot.send(chatId, content);
+    return msg.id;
   }
-}
 
-// 2. Connect to the VibeAround host
-const renderer = new MyRenderer({ minEditIntervalMs: 600 });
-
-const { agent, meta, agentInfo, conn } = await connectToHost(
-  { name: "vibearound-myplatform", version: "0.1.0" },
-  (_agent) => ({
-    async sessionUpdate(params: SessionNotification) {
-      renderer.onSessionUpdate(params);
-    },
-    async requestPermission(params) {
-      return { outcome: { outcome: "selected", optionId: params.options![0].optionId } };
-    },
-    async extNotification(method, params) {
-      switch (normalizeExtMethod(method)) {
-        case "channel/system_text":
-          await myPlatform.send(params.channelId as string, params.text as string);
-          break;
-      }
-    },
-  }),
-);
-
-// 3. Use the config and start your platform bot
-const botToken = meta.config.bot_token as string;
-// ... initialize your platform SDK ...
-
-// 4. On each incoming message:
-renderer.onPromptSent(channelId);
-try {
-  await agent.prompt({ sessionId: chatId, prompt: contentBlocks });
-  await renderer.onTurnEnd(channelId);
-} catch (e) {
-  await renderer.onTurnError(channelId, String(e));
+  protected async editBlock(chatId: string, ref: string, kind: BlockKind, content: string, sealed: boolean) {
+    await this.bot.edit(chatId, ref, content);
+  }
 }
 
-// 5. Keep alive until host disconnects
-await conn.closed;
+// 2. Run the plugin
+runChannelPlugin({
+  name: "vibearound-myplatform",
+  version: "0.1.0",
+  requiredConfig: ["bot_token"],
+  createBot: ({ config, agent, log, cacheDir }) =>
+    new MyBot(config.bot_token as string, agent, log, cacheDir),
+  createRenderer: (bot, log, verbose) =>
+    new MyRenderer(bot, log, verbose),
+});
 ```
 
+That's it. The SDK handles ACP connection, config validation, event routing, and shutdown.
+
 ## BlockRenderer
 
-The `BlockRenderer<TRef>` groups streaming ACP events into contiguous blocks by kind (`text`, `thinking`, `tool`), then renders them to your platform via `sendBlock` / `editBlock`.
+Abstract base class that renders agent responses to your IM platform.
 
-### Constructor options
+### Required methods
 
-| Option | Default | Description |
+| Method | Description |
+|---|---|
+| `sendText(chatId, text)` | Send a plain text message (system notifications, errors) |
+| `sendBlock(chatId, kind, content)` | Send a new streaming block, return a platform ref for editing |
+
+### Optional methods
+
+| Method | Default | Description |
 |---|---|---|
-| `flushIntervalMs` | `500` | Debounce interval before flushing an in-progress block |
-| `minEditIntervalMs` | `1000` | Minimum gap between consecutive edits (rate limit protection) |
-| `verbose.showThinking` | `false` | Render agent thinking/reasoning blocks |
-| `verbose.showToolUse` | `false` | Render tool call/result blocks |
+| `editBlock(chatId, ref, kind, content, sealed)` | — | Edit a message in-place (omit for send-only platforms) |
+| `formatContent(kind, content, sealed)` | Emoji prefixes | Format block content before send/edit |
+| `onAfterTurnEnd(chatId)` | No-op | Cleanup after turn completes |
+| `onAfterTurnError(chatId, error)` | `sendText(chatId, "❌ ...")` | Custom error rendering |
+| `onCommandMenu(chatId, systemCmds, agentCmds)` | Plain text list | Custom command menu rendering |
 
-### Methods to implement
+### Constructor options
 
-| Method | Required | Description |
+| Option | Default | Description |
 |---|---|---|
-| `sendBlock(channelId, kind, content)` | Yes | Send a new message, return a platform ref (or `null` if no editing) |
-| `editBlock(channelId, ref, kind, content, sealed)` | No | Edit an existing message in-place |
-| `formatContent(kind, content, sealed)` | No | Format block content before send/edit (default: emoji prefixes) |
+| `streaming` | `true` | `true`: send + edit in real-time. `false`: hold each block until complete, then send once |
+| `flushIntervalMs` | `500` | Debounce interval before flushing |
+| `minEditIntervalMs` | `1000` | Minimum gap between edits (rate limit protection) |
+| `verbose.showThinking` | `false` | Show agent thinking blocks |
+| `verbose.showToolUse` | `false` | Show tool call blocks |
 
-### Lifecycle hooks
+## ChannelBot interface
 
-| Hook | Description |
-|---|---|
-| `onAfterTurnEnd(channelId)` | Cleanup after all blocks are flushed (e.g. remove typing indicator) |
-| `onAfterTurnError(channelId, error)` | Send error message to user |
-| `sessionIdToChannelId(sessionId)` | Map ACP session ID to your channel ID (default: identity) |
-
-## Plugin manifest
-
-Each channel plugin needs a `plugin.json` at its root:
-
-```json
-{
-  "id": "my-platform",
-  "name": "My Platform Channel",
-  "version": "0.1.0",
-  "kind": "channel",
-  "runtime": "node",
-  "entry": "dist/main.js",
-  "build": "npm install && npm run build",
-  "configSchema": {
-    "type": "object",
-    "properties": {
-      "bot_token": { "type": "string" }
-    },
-    "required": ["bot_token"]
-  },
-  "capabilities": {
-    "streaming": true,
-    "editMessage": true,
-    "media": false
-  }
+Your bot class should implement:
+
+```ts
+interface ChannelBot {
+  setStreamHandler(handler: BlockRenderer): void;
+  start(): Promise<void> | void;
+  stop(): Promise<void> | void;
 }
 ```
 
-## Examples
+## Advanced usage
 
-See the official channel plugins for real-world usage:
+For plugins that need custom ACP lifecycle control:
 
-- **Feishu** — Interactive cards, streaming updates, reactions
-- **Telegram** — Plain text messages with inline editing
-- **WeChat** — Send-only mode (no editing), typing indicators
+```ts
+import { connectToHost, stripExtPrefix } from "@vibearound/plugin-channel-sdk/advanced";
+```
 
 ## License
 

package/dist/advanced.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @vibearound/plugin-channel-sdk — Advanced / low-level API
+ *
+ * For plugins that need custom ACP lifecycle control instead of
+ * the standard `runChannelPlugin()` flow.
+ *
+ * Normal plugins should use the main entry point instead:
+ * ```ts
+ * import { runChannelPlugin, BlockRenderer } from "@vibearound/plugin-channel-sdk";
+ * ```
+ */
+export { connectToHost, stripExtPrefix, redirectConsoleToStderr } from "./connection.js";
+export type { PluginInfo, ConnectResult, AgentInfo } from "./connection.js";
+export type { Agent, Client, ContentBlock, SessionNotification, RequestPermissionRequest, RequestPermissionResponse, BlockKind, VerboseConfig, BlockRendererOptions, PluginCapabilities, PluginManifest, PluginInitMeta, } from "./types.js";
+export { runChannelPlugin } from "./plugin.js";
+export { BlockRenderer } from "./renderer.js";
+export { extractErrorMessage } from "./errors.js";
+export type { ChannelBot, ChannelPluginLogger, CreateBotContext, RunChannelPluginSpec, VerboseOptions, } from "./plugin.js";
+//# sourceMappingURL=advanced.d.ts.map

package/dist/advanced.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"advanced.d.ts","sourceRoot":"","sources":["../src/advanced.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AACzF,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAG5E,YAAY,EACV,KAAK,EACL,MAAM,EACN,YAAY,EACZ,mBAAmB,EACnB,wBAAwB,EACxB,yBAAyB,EACzB,SAAS,EACT,aAAa,EACb,oBAAoB,EACpB,kBAAkB,EAClB,cAAc,EACd,cAAc,GACf,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,YAAY,EACV,UAAU,EACV,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,cAAc,GACf,MAAM,aAAa,CAAC"}

package/dist/advanced.js

@@ -0,0 +1,18 @@
+/**
+ * @vibearound/plugin-channel-sdk — Advanced / low-level API
+ *
+ * For plugins that need custom ACP lifecycle control instead of
+ * the standard `runChannelPlugin()` flow.
+ *
+ * Normal plugins should use the main entry point instead:
+ * ```ts
+ * import { runChannelPlugin, BlockRenderer } from "@vibearound/plugin-channel-sdk";
+ * ```
+ */
+// Low-level ACP connection
+export { connectToHost, stripExtPrefix, redirectConsoleToStderr } from "./connection.js";
+// Re-export high-level API too (so advanced users don't need two imports)
+export { runChannelPlugin } from "./plugin.js";
+export { BlockRenderer } from "./renderer.js";
+export { extractErrorMessage } from "./errors.js";
+//# sourceMappingURL=advanced.js.map

package/dist/advanced.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"advanced.js","sourceRoot":"","sources":["../src/advanced.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,2BAA2B;AAC3B,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAmBzF,0EAA0E;AAC1E,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC"}

package/dist/connection.d.ts

@@ -52,11 +52,17 @@ export interface ConnectResult {
  */
 export declare function connectToHost(pluginInfo: PluginInfo, makeClient: (agent: Agent) => Client): Promise<ConnectResult>;
 /**
- * Normalize ACP ext notification method names.
+ * Strip the `_` prefix from ACP extension method names.
  *
- * The ACP SDK prepends "_" to ext method names (e.g. "_channel/system_text").
- * Strip the prefix to get the canonical method name used in plugin.json.
+ * The Rust ACP SDK adds `_` when sending ext notifications on the wire,
+ * but the TypeScript ACP SDK does not strip it on receipt. This function
+ * normalizes the received method name so handlers can match the canonical
+ * name (e.g. `_va/system_text` → `va/system_text`).
+ *
+ * Note: when sending ext notifications FROM TypeScript TO the Rust host,
+ * the method name must include the `_` prefix manually (e.g. `_va/callback`)
+ * because the TypeScript SDK does not add it automatically.
  */
-export declare function normalizeExtMethod(method: string): string;
+export declare function stripExtPrefix(method: string): string;
 export declare function redirectConsoleToStderr(): void;
 //# sourceMappingURL=connection.d.ts.map

package/dist/connection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAIL,KAAK,KAAK,EACV,KAAK,MAAM,EACZ,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAMjD,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,kEAAkE;IAClE,KAAK,EAAE,KAAK,CAAC;IACb,mEAAmE;IACnE,IAAI,EAAE,cAAc,CAAC;IACrB,4EAA4E;IAC5E,SAAS,EAAE,SAAS,CAAC;IACrB;;;OAGG;IACH,IAAI,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,aAAa,CACjC,UAAU,EAAE,UAAU,EACtB,UAAU,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,GACnC,OAAO,CAAC,aAAa,CAAC,CAqCxB;AAMD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEzD;AAWD,wBAAgB,uBAAuB,IAAI,IAAI,CAe9C"}
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAIL,KAAK,KAAK,EACV,KAAK,MAAM,EACZ,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAMjD,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,kEAAkE;IAClE,KAAK,EAAE,KAAK,CAAC;IACb,mEAAmE;IACnE,IAAI,EAAE,cAAc,CAAC;IACrB,4EAA4E;IAC5E,SAAS,EAAE,SAAS,CAAC;IACrB;;;OAGG;IACH,IAAI,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,aAAa,CACjC,UAAU,EAAE,UAAU,EACtB,UAAU,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,GACnC,OAAO,CAAC,aAAa,CAAC,CAqCxB;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAErD;AAWD,wBAAgB,uBAAuB,IAAI,IAAI,CAe9C"}

package/dist/connection.js

@@ -59,12 +59,18 @@ export async function connectToHost(pluginInfo, makeClient) {
 // Utilities
 // ---------------------------------------------------------------------------
 /**
- * Normalize ACP ext notification method names.
+ * Strip the `_` prefix from ACP extension method names.
  *
- * The ACP SDK prepends "_" to ext method names (e.g. "_channel/system_text").
- * Strip the prefix to get the canonical method name used in plugin.json.
+ * The Rust ACP SDK adds `_` when sending ext notifications on the wire,
+ * but the TypeScript ACP SDK does not strip it on receipt. This function
+ * normalizes the received method name so handlers can match the canonical
+ * name (e.g. `_va/system_text` → `va/system_text`).
+ *
+ * Note: when sending ext notifications FROM TypeScript TO the Rust host,
+ * the method name must include the `_` prefix manually (e.g. `_va/callback`)
+ * because the TypeScript SDK does not add it automatically.
  */
-export function normalizeExtMethod(method) {
+export function stripExtPrefix(method) {
     return method.startsWith("_") ? method.slice(1) : method;
 }
 /**

package/dist/connection.js.map

@@ -1 +1 @@
-{"version":3,"file":"connection.js","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,62 +1,45 @@
 /**
  * @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();
- *
- * 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;
- *         }
- *       },
- *     };
- *   },
- * );
- *
- * const botToken = meta.config.bot_token as string;
- * // … start your platform bot …
- * await conn.closed;
+ * 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
+ *
+ * For plugins that need custom ACP lifecycle control (e.g. weixin-openclaw-bridge),
+ * import from the `advanced` subpath:
+ *
+ * ```ts
+ * import { connectToHost } from "@vibearound/plugin-channel-sdk/advanced";
  * ```
  */
-export { connectToHost, normalizeExtMethod, redirectConsoleToStderr } from "./connection.js";
-export type { PluginInfo, ConnectResult, AgentInfo } from "./connection.js";
-export { extractErrorMessage } from "./errors.js";
-export { runChannelPlugin } from "./run-plugin.js";
-export type { ChannelBot, ChannelPluginLogger, ChannelStreamHandler, CreateBotContext, RunChannelPluginSpec, VerboseOptions, } from "./run-plugin.js";
+export { runChannelPlugin } from "./plugin.js";
 export { BlockRenderer } from "./renderer.js";
-export type { Agent, Client, ContentBlock, SessionNotification, RequestPermissionRequest, RequestPermissionResponse, BlockKind, VerboseConfig, BlockRendererOptions, PluginCapabilities, PluginManifest, PluginInitMeta, } from "./types.js";
+export type { ChannelBot, ChannelPluginLogger, CreateBotContext, RunChannelPluginSpec, VerboseOptions, } from "./plugin.js";
+export type { BlockKind, CommandEntry, VerboseConfig, BlockRendererOptions, } from "./types.js";
+export type { Agent, ContentBlock, SessionNotification, } from "./types.js";
+export { extractErrorMessage } from "./errors.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAGH,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAC7F,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAG5E,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAGlD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,YAAY,EACV,UAAU,EACV,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EAChB,oBAAoB,EACpB,cAAc,GACf,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAI9C,YAAY,EAEV,KAAK,EACL,MAAM,EACN,YAAY,EACZ,mBAAmB,EACnB,wBAAwB,EACxB,yBAAyB,EAEzB,SAAS,EACT,aAAa,EACb,oBAAoB,EACpB,kBAAkB,EAClB,cAAc,EACd,cAAc,GACf,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAOH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG/C,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAG9C,YAAY,EACV,UAAU,EACV,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,cAAc,GACf,MAAM,aAAa,CAAC;AAGrB,YAAY,EACV,SAAS,EACT,YAAY,EACZ,aAAa,EACb,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAGpB,YAAY,EACV,KAAK,EACL,YAAY,EACZ,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -1,63 +1,48 @@
 /**
  * @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();
- *
- * 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;
- *         }
- *       },
- *     };
- *   },
- * );
- *
- * const botToken = meta.config.bot_token as string;
- * // … start your platform bot …
- * await conn.closed;
+ * 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
+ *
+ * For plugins that need custom ACP lifecycle control (e.g. weixin-openclaw-bridge),
+ * import from the `advanced` subpath:
+ *
+ * ```ts
+ * import { connectToHost } from "@vibearound/plugin-channel-sdk/advanced";
  * ```
  */
-// Connection helpers
-export { connectToHost, normalizeExtMethod, redirectConsoleToStderr } from "./connection.js";
-// Error normalization
-export { extractErrorMessage } from "./errors.js";
-// Plugin runner (absorbs the main.ts boilerplate)
-export { runChannelPlugin } from "./run-plugin.js";
-// Block renderer
+// ---------------------------------------------------------------------------
+// High-level API — what plugin developers use
+// ---------------------------------------------------------------------------
+// Entry point
+export { runChannelPlugin } from "./plugin.js";
+// Base class for stream rendering
 export { BlockRenderer } from "./renderer.js";
+// Error utility
+export { extractErrorMessage } from "./errors.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,qBAAqB;AACrB,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAG7F,sBAAsB;AACtB,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAElD,kDAAkD;AAClD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAUnD,iBAAiB;AACjB,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,8EAA8E;AAC9E,8CAA8C;AAC9C,8EAA8E;AAE9E,cAAc;AACd,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,kCAAkC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AA0B9C,gBAAgB;AAChB,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC"}

package/dist/plugin.d.ts

@@ -0,0 +1,80 @@
+/**
+ * runChannelPlugin — the SDK entry point for every channel plugin.
+ *
+ * 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";
+ *
+ * runChannelPlugin({
+ *   name: "vibearound-slack",
+ *   version: "0.1.0",
+ *   requiredConfig: ["bot_token", "app_token"],
+ *   createBot: ({ config, agent, log, cacheDir }) =>
+ *     new SlackBot({ ... }, agent, log, cacheDir),
+ *   createRenderer: (bot, log, verbose) =>
+ *     new SlackRenderer(bot, log, verbose),
+ * });
+ * ```
+ */
+import type { Agent } from "@agentclientprotocol/sdk";
+import { BlockRenderer } from "./renderer.js";
+export type ChannelPluginLogger = (level: string, msg: string) => 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.
+ */
+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;
+}
+export interface CreateBotContext {
+    config: Record<string, unknown>;
+    agent: Agent;
+    log: ChannelPluginLogger;
+    cacheDir: string;
+}
+export interface VerboseOptions {
+    showThinking: boolean;
+    showToolUse: boolean;
+}
+export interface RunChannelPluginSpec<TBot extends ChannelBot<TRenderer>, TRenderer extends BlockRenderer<any>> {
+    /** Plugin name reported during ACP initialize (e.g. "vibearound-slack"). */
+    name: string;
+    /** Plugin version reported during ACP initialize. */
+    version: string;
+    /**
+     * Config keys that MUST be present. Plugin fails fast if any are missing.
+     */
+    requiredConfig?: string[];
+    /** Factory: build the platform bot. */
+    createBot: (ctx: CreateBotContext) => TBot | Promise<TBot>;
+    /**
+     * Factory: build the renderer (extends BlockRenderer).
+     * Only implements platform-specific sendText/sendBlock/editBlock.
+     */
+    createRenderer: (bot: TBot, log: ChannelPluginLogger, verbose: VerboseOptions) => TRenderer;
+    /**
+     * Optional hook invoked after bot constructed but before start().
+     */
+    afterCreate?: (bot: TBot, log: ChannelPluginLogger) => Promise<void> | void;
+}
+/**
+ * Run a channel plugin.
+ *
+ * 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 declare function runChannelPlugin<TBot extends ChannelBot<TRenderer>, TRenderer extends BlockRenderer<any>>(spec: RunChannelPluginSpec<TBot, TRenderer>): Promise<void>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AAItD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAW9C,MAAM,MAAM,mBAAmB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;AAEvE;;;;;GAKG;AAEH,MAAM,WAAW,UAAU,CAAC,SAAS,SAAS,aAAa,CAAC,GAAG,CAAC,GAAG,aAAa,CAAC,GAAG,CAAC;IACnF,qDAAqD;IACrD,gBAAgB,CAAC,OAAO,EAAE,SAAS,GAAG,IAAI,CAAC;IAC3C,+DAA+D;IAC/D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC9B,+BAA+B;IAC/B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,KAAK,EAAE,KAAK,CAAC;IACb,GAAG,EAAE,mBAAmB,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,OAAO,CAAC;IACtB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB,CACnC,IAAI,SAAS,UAAU,CAAC,SAAS,CAAC,EAClC,SAAS,SAAS,aAAa,CAAC,GAAG,CAAC;IAEpC,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IAEb,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAE1B,uCAAuC;IACvC,SAAS,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3D;;;OAGG;IACH,cAAc,EAAE,CACd,GAAG,EAAE,IAAI,EACT,GAAG,EAAE,mBAAmB,EACxB,OAAO,EAAE,cAAc,KACpB,SAAS,CAAC;IAEf;;OAEG;IACH,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,mBAAmB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC7E;AAMD;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,SAAS,UAAU,CAAC,SAAS,CAAC,EAClC,SAAS,SAAS,aAAa,CAAC,GAAG,CAAC,EACpC,IAAI,EAAE,oBAAoB,CAAC,IAAI,EAAE,SAAS,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAY5D"}