@vibearound/plugin-channel-sdk 0.1.0

package/dist/renderer.js

@@ -0,0 +1,317 @@
+/**
+ * BlockRenderer — abstract base class for block-based message rendering.
+ *
+ * ## How it works
+ *
+ * ACP streams agent responses as a sequence of typed events:
+ *   text chunk, text chunk, tool call, tool update, text chunk, …
+ *
+ * Each contiguous run of the **same kind** (text / thinking / tool) is grouped
+ * into one "block". When the kind changes, the current block is **sealed**
+ * (no more edits) and a new block starts.
+ *
+ * Blocks are rendered to the platform by subclass-implemented `sendBlock` and
+ * `editBlock`. The renderer handles:
+ *
+ *   - **Debounced flushing** — batches rapid deltas before sending (avoids
+ *     excessive API calls during fast streaming).
+ *   - **Edit throttling** — enforces a minimum interval between edits to
+ *     respect platform rate limits.
+ *   - **Ordered delivery** — a `sendChain` Promise serializes all send/edit
+ *     calls so messages always arrive in the correct order.
+ *   - **Sentinel guard** — prevents concurrent creates for the same block.
+ *   - **Verbose filtering** — thinking / tool blocks can be suppressed without
+ *     creating phantom block boundaries.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * class MyRenderer extends BlockRenderer<string> {
+ *   protected async sendBlock(channelId, kind, content) {
+ *     const msg = await myApi.sendMessage(channelId, content);
+ *     return msg.id;
+ *   }
+ *   protected async editBlock(channelId, ref, kind, content, sealed) {
+ *     await myApi.editMessage(ref, content);
+ *   }
+ * }
+ *
+ * // In main.ts:
+ * const renderer = new MyRenderer({ verbose: { showThinking: false } });
+ *
+ * // When user sends a message:
+ * renderer.onPromptSent(channelId);
+ * try {
+ *   await agent.prompt({ sessionId, content });
+ *   await renderer.onTurnEnd(channelId);
+ * } catch (e) {
+ *   await renderer.onTurnError(channelId, String(e));
+ * }
+ *
+ * // In the ACP client's sessionUpdate handler:
+ * renderer.onSessionUpdate(notification);
+ * ```
+ */
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const DEFAULT_FLUSH_INTERVAL_MS = 500;
+const DEFAULT_MIN_EDIT_INTERVAL_MS = 1000;
+// ---------------------------------------------------------------------------
+// BlockRenderer
+// ---------------------------------------------------------------------------
+/**
+ * Abstract base class for block-based rendering of ACP session streams.
+ *
+ * @typeParam TRef - Platform-specific message reference type (e.g. `number`
+ *   for Telegram message IDs, `string` for Feishu message IDs). Used as the
+ *   return type of `sendBlock` and the first argument of `editBlock`.
+ */
+export class BlockRenderer {
+    flushIntervalMs;
+    minEditIntervalMs;
+    verbose;
+    states = new Map();
+    constructor(options = {}) {
+        this.flushIntervalMs = options.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS;
+        this.minEditIntervalMs = options.minEditIntervalMs ?? DEFAULT_MIN_EDIT_INTERVAL_MS;
+        this.verbose = {
+            showThinking: options.verbose?.showThinking ?? false,
+            showToolUse: options.verbose?.showToolUse ?? false,
+        };
+    }
+    /**
+     * Format block content before sending or editing.
+     *
+     * Default applies standard emoji prefixes:
+     *   - `thinking` → `💭 <content>`
+     *   - `tool`     → trimmed content
+     *   - `text`     → content as-is
+     *
+     * Override to apply platform-specific formatting (e.g. markdown escaping).
+     */
+    formatContent(kind, content, _sealed) {
+        switch (kind) {
+            case "thinking": return `💭 ${content}`;
+            case "tool": return content.trim();
+            case "text": return content;
+        }
+    }
+    /**
+     * Called after the last block has been flushed and the turn is complete.
+     * Override to perform cleanup (e.g. remove a "typing" indicator, a
+     * processing reaction, etc.).
+     */
+    onAfterTurnEnd(_channelId) {
+        return Promise.resolve();
+    }
+    /**
+     * Called after a turn error, once state has been cleaned up.
+     * Override to send an error message to the user.
+     */
+    onAfterTurnError(_channelId, _error) {
+        return Promise.resolve();
+    }
+    /**
+     * Map an ACP `sessionId` to the channel ID used internally.
+     *
+     * Default: identity (sessionId === channelId).
+     *
+     * Override if your plugin namespaces channel IDs (e.g. Feishu uses
+     * `"feishu:<sessionId>"`, WeChat uses `"weixin-openclaw-bridge:<sessionId>"`).
+     */
+    sessionIdToChannelId(sessionId) {
+        return sessionId;
+    }
+    // ---------------------------------------------------------------------------
+    // Public API
+    // ---------------------------------------------------------------------------
+    /**
+     * Process an ACP `sessionUpdate` notification from the host.
+     *
+     * Routes the event to the correct block based on its variant, appending
+     * deltas to the current block or starting a new one when the kind changes.
+     *
+     * Call this from the ACP `Client.sessionUpdate` handler.
+     */
+    onSessionUpdate(notification) {
+        const sessionId = notification.sessionId;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const update = notification.update;
+        const variant = update.sessionUpdate;
+        const channelId = this.sessionIdToChannelId(sessionId);
+        switch (variant) {
+            case "agent_message_chunk": {
+                const delta = (update.content?.text ?? "");
+                if (delta)
+                    this.appendToBlock(channelId, "text", delta);
+                break;
+            }
+            case "agent_thought_chunk": {
+                if (!this.verbose.showThinking)
+                    return; // skip — no block, no boundary
+                const delta = (update.content?.text ?? "");
+                if (delta)
+                    this.appendToBlock(channelId, "thinking", delta);
+                break;
+            }
+            case "tool_call": {
+                if (!this.verbose.showToolUse)
+                    return; // skip
+                const title = update.title;
+                if (title)
+                    this.appendToBlock(channelId, "tool", `🔧 ${title}\n`);
+                break;
+            }
+            case "tool_call_update": {
+                if (!this.verbose.showToolUse)
+                    return; // skip
+                const title = (update.title ?? "tool");
+                const status = update.status;
+                if (status === "completed" || status === "error") {
+                    this.appendToBlock(channelId, "tool", `✅ ${title}\n`);
+                }
+                break;
+            }
+        }
+    }
+    /**
+     * Call this before sending a prompt to the agent.
+     *
+     * Clears any leftover state from a previous turn so the new turn starts
+     * with a clean slate.
+     */
+    onPromptSent(channelId) {
+        const old = this.states.get(channelId);
+        if (old?.flushTimer)
+            clearTimeout(old.flushTimer);
+        this.states.set(channelId, {
+            blocks: [],
+            flushTimer: null,
+            lastEditMs: 0,
+            sendChain: Promise.resolve(),
+        });
+    }
+    /**
+     * Call this after `agent.prompt()` resolves (turn complete).
+     *
+     * Seals and flushes the last block, then waits for all pending sends/edits
+     * to complete before calling `onAfterTurnEnd`.
+     */
+    async onTurnEnd(channelId) {
+        const state = this.states.get(channelId);
+        if (!state)
+            return;
+        if (state.flushTimer) {
+            clearTimeout(state.flushTimer);
+            state.flushTimer = null;
+        }
+        const last = state.blocks.at(-1);
+        if (last && !last.sealed) {
+            last.sealed = true;
+            this.enqueueFlush(state, last);
+        }
+        // Wait for the entire chain to drain before cleanup
+        await state.sendChain;
+        this.states.delete(channelId);
+        await this.onAfterTurnEnd(channelId);
+    }
+    /**
+     * Call this when `agent.prompt()` throws (turn error).
+     *
+     * Discards pending state and calls `onAfterTurnError` so the subclass can
+     * send an error message to the user.
+     */
+    async onTurnError(channelId, error) {
+        const state = this.states.get(channelId);
+        if (state?.flushTimer)
+            clearTimeout(state.flushTimer);
+        this.states.delete(channelId);
+        await this.onAfterTurnError(channelId, error);
+    }
+    // ---------------------------------------------------------------------------
+    // Internal — block management
+    // ---------------------------------------------------------------------------
+    appendToBlock(channelId, kind, delta) {
+        let state = this.states.get(channelId);
+        if (!state) {
+            // Auto-create state if onPromptSent wasn't called (e.g. host-initiated turns)
+            state = { blocks: [], flushTimer: null, lastEditMs: 0, sendChain: Promise.resolve() };
+            this.states.set(channelId, state);
+        }
+        const last = state.blocks.at(-1);
+        if (last && !last.sealed && last.kind === kind) {
+            // Same kind — accumulate
+            last.content += delta;
+        }
+        else {
+            // Kind changed — seal current block and start a new one
+            if (last && !last.sealed) {
+                last.sealed = true;
+                // Clear the debounce timer: we're doing an immediate flush of the sealed block
+                if (state.flushTimer) {
+                    clearTimeout(state.flushTimer);
+                    state.flushTimer = null;
+                }
+                this.enqueueFlush(state, last);
+            }
+            state.blocks.push({ channelId, kind, content: delta, ref: null, creating: false, sealed: false });
+        }
+        this.scheduleFlush(channelId, state);
+    }
+    scheduleFlush(channelId, state) {
+        if (state.flushTimer)
+            return; // already scheduled
+        state.flushTimer = setTimeout(() => {
+            state.flushTimer = null;
+            this.flush(channelId, state);
+        }, this.flushIntervalMs);
+    }
+    flush(channelId, state) {
+        const block = state.blocks.at(-1);
+        if (!block || block.sealed || !block.content)
+            return;
+        const now = Date.now();
+        if (now - state.lastEditMs < this.minEditIntervalMs) {
+            // Throttled — reschedule for the remaining window
+            const delay = this.minEditIntervalMs - (now - state.lastEditMs);
+            if (!state.flushTimer) {
+                state.flushTimer = setTimeout(() => {
+                    state.flushTimer = null;
+                    this.flush(channelId, state);
+                }, delay);
+            }
+            return;
+        }
+        this.enqueueFlush(state, block);
+    }
+    enqueueFlush(state, block) {
+        state.sendChain = state.sendChain
+            .then(() => this.flushBlock(state, block))
+            .catch(() => { }); // errors are handled inside flushBlock
+    }
+    async flushBlock(state, block) {
+        const content = this.formatContent(block.kind, block.content, block.sealed);
+        if (!content)
+            return;
+        try {
+            if (block.ref === null && !block.creating) {
+                // First send — use sentinel to prevent concurrent creates
+                block.creating = true;
+                block.ref = await this.sendBlock(block.channelId, block.kind, content);
+                block.creating = false;
+                state.lastEditMs = Date.now();
+            }
+            else if (block.ref !== null && !block.creating && this.editBlock) {
+                // Subsequent update — edit in-place
+                await this.editBlock(block.channelId, block.ref, block.kind, content, block.sealed);
+                state.lastEditMs = Date.now();
+            }
+            // else: create is in-flight (creating === true) — skip
+        }
+        catch {
+            block.creating = false;
+        }
+    }
+}
+//# sourceMappingURL=renderer.js.map

package/dist/renderer.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Shared types for VibeAround channel plugins.
+ *
+ * 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 interface PluginCapabilities {
+    /** Plugin supports real-time streaming updates. */
+    streaming?: boolean;
+    /** Platform supports rich interactive cards (e.g. Feishu). */
+    interactiveCards?: boolean;
+    /** Platform supports editing already-sent messages. */
+    editMessage?: boolean;
+    /** Platform supports file upload/download. */
+    media?: boolean;
+    auth?: {
+        methods?: string[];
+    };
+}
+/** Shape of plugin.json — the plugin manifest file. */
+export interface PluginManifest {
+    id: string;
+    name: string;
+    kind: "channel";
+    runtime: "node";
+    entry: string;
+    build?: string;
+    configSchema?: Record<string, unknown>;
+    capabilities?: PluginCapabilities;
+}
+/** The three kinds of content blocks a plugin renders. */
+export type BlockKind = "text" | "thinking" | "tool";
+export interface VerboseConfig {
+    /** Show agent thinking/reasoning blocks. Default: false. */
+    showThinking: boolean;
+    /** Show tool call / tool result blocks. Default: false. */
+    showToolUse: boolean;
+}
+export interface BlockRendererOptions {
+    /**
+     * Debounce interval before flushing an unsealed block (ms).
+     * Controls how often in-progress blocks are sent to the platform.
+     * Default: 500.
+     */
+    flushIntervalMs?: number;
+    /**
+     * Minimum interval between consecutive edits to the same message (ms).
+     * Prevents hitting platform API rate limits.
+     * Default: 1000.
+     */
+    minEditIntervalMs?: number;
+    verbose?: Partial<VerboseConfig>;
+}
+/**
+ * Plugin config and metadata passed by the host in `_meta` during initialize.
+ */
+export interface PluginInitMeta {
+    /** Plugin-specific config object from settings.json. */
+    config: Record<string, unknown>;
+    /** Host-provided cache directory path for temporary files. */
+    cacheDir?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +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"}

package/dist/types.js

@@ -0,0 +1,8 @@
+/**
+ * Shared types for VibeAround channel plugins.
+ *
+ * Re-exports the ACP SDK types plugins commonly need, plus SDK-specific types
+ * for block rendering, plugin manifests, and verbose configuration.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@vibearound/plugin-channel-sdk",
+  "version": "0.1.0",
+  "description": "VibeAround Plugin SDK — base classes and utilities for building channel plugins",
+  "license": "MIT",
+  "type": "module",
+  "files": ["dist", "src"],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@agentclientprotocol/sdk": "^0.17.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/src/connection.ts

@@ -0,0 +1,147 @@
+/**
+ * ACP stdio connection helpers.
+ *
+ * Handles the boilerplate of wiring Node.js stdio streams to an ACP
+ * ClientSideConnection, performing the initialize handshake, and extracting
+ * plugin config from the host's _meta response.
+ */
+
+import { Readable, Writable } from "node:stream";
+import {
+  ClientSideConnection,
+  ndJsonStream,
+  PROTOCOL_VERSION,
+  type Agent,
+  type Client,
+} from "@agentclientprotocol/sdk";
+import type { PluginInitMeta } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface PluginInfo {
+  name: string;
+  version: string;
+}
+
+export interface AgentInfo {
+  name?: string;
+  version?: string;
+}
+
+export interface ConnectResult {
+  /** ACP agent reference — call agent.prompt() to send messages. */
+  agent: Agent;
+  /** Plugin config and cache dir provided by the host at startup. */
+  meta: PluginInitMeta;
+  /** Info about the host agent (name, version) reported during initialize. */
+  agentInfo: AgentInfo;
+  /**
+   * The ACP connection. Await `conn.closed` to keep the process alive until
+   * the host disconnects.
+   */
+  conn: { readonly closed: Promise<void> };
+}
+
+/**
+ * Connect to the VibeAround host via stdio ACP.
+ *
+ * Sets up Node.js stdio streams → ACP transport, calls `initialize`, and
+ * returns the agent reference plus plugin config/meta from the host.
+ *
+ * @param pluginInfo - Name and version reported to the host
+ * @param makeClient - Factory called with the Agent; returns the Client
+ *   implementation (sessionUpdate, requestPermission, extNotification).
+ *   Capture the agent argument here if you need it before this function resolves.
+ *
+ * @example
+ * ```ts
+ * let agent!: Agent;
+ * const { meta, conn } = await connectToHost(
+ *   { name: "vibearound-mybot", version: "0.1.0" },
+ *   (a) => { agent = a; return myClient; },
+ * );
+ * ```
+ */
+export async function connectToHost(
+  pluginInfo: PluginInfo,
+  makeClient: (agent: Agent) => Client,
+): Promise<ConnectResult> {
+  // Keep stdout clean for JSON-RPC — redirect all console output to stderr
+  redirectConsoleToStderr();
+
+  const inputStream = Readable.toWeb(process.stdin) as ReadableStream<Uint8Array>;
+  const outputStream = Writable.toWeb(process.stdout) as WritableStream<Uint8Array>;
+  const stream = ndJsonStream(outputStream, inputStream);
+
+  let capturedAgent!: Agent;
+  const wrappedMakeClient = (a: Agent): Client => {
+    capturedAgent = a;
+    return makeClient(a);
+  };
+
+  const conn = new ClientSideConnection(wrappedMakeClient, stream);
+
+  const initResponse = await conn.initialize({
+    protocolVersion: PROTOCOL_VERSION,
+    clientInfo: { name: pluginInfo.name, version: pluginInfo.version },
+    capabilities: {},
+  });
+
+  const rawMeta = (initResponse as Record<string, unknown>)._meta as
+    | Record<string, unknown>
+    | undefined;
+
+  const meta: PluginInitMeta = {
+    config: (rawMeta?.config ?? {}) as Record<string, unknown>,
+    cacheDir: rawMeta?.cacheDir as string | undefined,
+  };
+
+  const agentInfo: AgentInfo = {
+    name: initResponse.agentInfo?.name,
+    version: initResponse.agentInfo?.version,
+  };
+
+  return { agent: capturedAgent, meta, agentInfo, conn };
+}
+
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalize ACP ext notification 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.
+ */
+export function normalizeExtMethod(method: string): string {
+  return method.startsWith("_") ? method.slice(1) : method;
+}
+
+/**
+ * Redirect all console.* output to stderr.
+ *
+ * ACP uses stdout for JSON-RPC framing — any stray console output corrupts
+ * the protocol. Call this once at plugin startup (connectToHost does this
+ * automatically).
+ */
+let _consoleRedirected = false;
+
+export function redirectConsoleToStderr(): void {
+  if (_consoleRedirected) return;
+  _consoleRedirected = true;
+
+  const toStderr = (...args: unknown[]) =>
+    process.stderr.write(args.map(String).join(" ") + "\n");
+
+  console.log = toStderr;
+  console.info = toStderr;
+  console.warn = (...args: unknown[]) =>
+    process.stderr.write("[warn] " + args.map(String).join(" ") + "\n");
+  console.error = (...args: unknown[]) =>
+    process.stderr.write("[error] " + args.map(String).join(" ") + "\n");
+  console.debug = (...args: unknown[]) =>
+    process.stderr.write("[debug] " + args.map(String).join(" ") + "\n");
+}

package/src/index.ts

@@ -0,0 +1,78 @@
+/**
+ * @vibearound/plugin-channel-sdk
+ *
+ * Base classes and utilities for building VibeAround channel plugins.
+ *
+ * ## Quick start
+ *
+ * ```ts
+ * import {
+ *   connectToHost,
+ *   BlockRenderer,
+ *   normalizeExtMethod,
+ *   type Agent,
+ *   type SessionNotification,
+ * } 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);
+ *   }
+ * }
+ *
+ * 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;
+ * ```
+ */
+
+// Connection helpers
+export { connectToHost, normalizeExtMethod, redirectConsoleToStderr } from "./connection.js";
+export type { PluginInfo, ConnectResult, AgentInfo } from "./connection.js";
+
+// Block renderer
+export { BlockRenderer } from "./renderer.js";
+
+// Types (re-exports ACP SDK types + SDK-specific types)
+export type {
+  // ACP SDK
+  Agent,
+  Client,
+  SessionNotification,
+  RequestPermissionRequest,
+  RequestPermissionResponse,
+  // SDK
+  BlockKind,
+  VerboseConfig,
+  BlockRendererOptions,
+  PluginCapabilities,
+  PluginManifest,
+  PluginInitMeta,
+} from "./types.js";