@vibearound/plugin-channel-sdk 0.1.0 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present VibeAround Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,151 @@
+# @vibearound/plugin-channel-sdk
+
+Base classes and utilities for building [VibeAround](https://github.com/anthropics/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.
+
+## Install
+
+```bash
+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";
+
+// 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
+  }
+
+  // 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);
+  }
+}
+
+// 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));
+}
+
+// 5. Keep alive until host disconnects
+await conn.closed;
+```
+
+## 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`.
+
+### Constructor options
+
+| Option | 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 |
+
+### Methods to implement
+
+| Method | Required | 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) |
+
+### Lifecycle hooks
+
+| 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
+  }
+}
+```
+
+## Examples
+
+See the official channel plugins for real-world usage:
+
+- **Feishu** — Interactive cards, streaming updates, reactions
+- **Telegram** — Plain text messages with inline editing
+- **WeChat** — Send-only mode (no editing), typing indicators
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -55,5 +55,5 @@
 export { connectToHost, normalizeExtMethod, redirectConsoleToStderr } from "./connection.js";
 export type { PluginInfo, ConnectResult, AgentInfo } from "./connection.js";
 export { BlockRenderer } from "./renderer.js";
-export type { Agent, Client, SessionNotification, RequestPermissionRequest, RequestPermissionResponse, BlockKind, VerboseConfig, BlockRendererOptions, PluginCapabilities, PluginManifest, PluginInitMeta, } from "./types.js";
+export type { Agent, Client, ContentBlock, SessionNotification, RequestPermissionRequest, RequestPermissionResponse, BlockKind, VerboseConfig, BlockRendererOptions, PluginCapabilities, PluginManifest, PluginInitMeta, } from "./types.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,aAAa,EAAE,MAAM,eAAe,CAAC;AAG9C,YAAY,EAEV,KAAK,EACL,MAAM,EACN,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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,aAAa,EAAE,MAAM,eAAe,CAAC;AAG9C,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"}

package/dist/types.d.ts

@@ -4,7 +4,7 @@
  * Re-exports the ACP SDK types plugins commonly need, plus SDK-specific types
  * for block rendering, plugin manifests, and verbose configuration.
  */
-export type { Agent, Client, SessionNotification, RequestPermissionRequest, RequestPermissionResponse, } from "@agentclientprotocol/sdk";
+export type { Agent, Client, ContentBlock, SessionNotification, RequestPermissionRequest, RequestPermissionResponse, } from "@agentclientprotocol/sdk";
 export interface PluginCapabilities {
     /** Plugin supports real-time streaming updates. */
     streaming?: boolean;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,YAAY,EACV,KAAK,EACL,MAAM,EACN,mBAAmB,EACnB,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,0BAA0B,CAAC;AAMlC,MAAM,WAAW,kBAAkB;IACjC,mDAAmD;IACnD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,uDAAuD;IACvD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,8CAA8C;IAC9C,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;CAC/B;AAED,uDAAuD;AACvD,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,YAAY,CAAC,EAAE,kBAAkB,CAAC;CACnC;AAMD,0DAA0D;AAC1D,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,CAAC;AAErD,MAAM,WAAW,aAAa;IAC5B,4DAA4D;IAC5D,YAAY,EAAE,OAAO,CAAC;IACtB,2DAA2D;IAC3D,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,OAAO,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;CAClC;AAMD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,YAAY,EACV,KAAK,EACL,MAAM,EACN,YAAY,EACZ,mBAAmB,EACnB,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,0BAA0B,CAAC;AAMlC,MAAM,WAAW,kBAAkB;IACjC,mDAAmD;IACnD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,uDAAuD;IACvD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,8CAA8C;IAC9C,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;CAC/B;AAED,uDAAuD;AACvD,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,YAAY,CAAC,EAAE,kBAAkB,CAAC;CACnC;AAMD,0DAA0D;AAC1D,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,CAAC;AAErD,MAAM,WAAW,aAAa;IAC5B,4DAA4D;IAC5D,YAAY,EAAE,OAAO,CAAC;IACtB,2DAA2D;IAC3D,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,OAAO,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;CAClC;AAMD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@vibearound/plugin-channel-sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "VibeAround Plugin SDK — base classes and utilities for building channel plugins",
   "license": "MIT",
   "type": "module",
-  "files": ["dist", "src"],
+  "files": [
+    "dist",
+    "src"
+  ],
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {

package/src/index.ts

@@ -65,6 +65,7 @@ export type {
   // ACP SDK
   Agent,
   Client,
+  ContentBlock,
   SessionNotification,
   RequestPermissionRequest,
   RequestPermissionResponse,

package/src/types.ts

@@ -9,6 +9,7 @@
 export type {
   Agent,
   Client,
+  ContentBlock,
   SessionNotification,
   RequestPermissionRequest,
   RequestPermissionResponse,