@vibearound/plugin-channel-sdk 0.1.0

package/src/renderer.ts

@@ -0,0 +1,395 @@
+/**
+ * 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);
+ * ```
+ */
+
+import type { SessionNotification } from "@agentclientprotocol/sdk";
+import type { BlockKind, BlockRendererOptions, VerboseConfig } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Internal state types
+// ---------------------------------------------------------------------------
+
+interface ManagedBlock<TRef> {
+  /** Channel this block belongs to. Captured at creation time. */
+  channelId: string;
+  kind: BlockKind;
+  content: string;
+  /** Platform message reference set after the first successful send. */
+  ref: TRef | null;
+  /** True while a create request is in-flight (prevents concurrent creates). */
+  creating: boolean;
+  /** True once the block will receive no more content. */
+  sealed: boolean;
+}
+
+interface ChannelState<TRef> {
+  blocks: ManagedBlock<TRef>[];
+  flushTimer: ReturnType<typeof setTimeout> | null;
+  /** Timestamp of the last successful send or edit (for throttle calculation). */
+  lastEditMs: number;
+  /** Serializes all send/edit calls — guarantees message order. */
+  sendChain: Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// 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 abstract class BlockRenderer<TRef = string> {
+  protected readonly flushIntervalMs: number;
+  protected readonly minEditIntervalMs: number;
+  protected readonly verbose: VerboseConfig;
+
+  private states = new Map<string, ChannelState<TRef>>();
+
+  constructor(options: BlockRendererOptions = {}) {
+    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,
+    };
+  }
+
+  // ---------------------------------------------------------------------------
+  // Abstract / overridable — subclass implements these
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Send a new block message to the platform.
+   *
+   * Return the platform message reference that will be passed to future
+   * `editBlock` calls. Return `null` if editing is not supported.
+   */
+  protected abstract sendBlock(
+    channelId: string,
+    kind: BlockKind,
+    content: string,
+  ): Promise<TRef | null>;
+
+  /**
+   * Edit an existing block message in-place.
+   *
+   * Optional — if not implemented, blocks are never edited (send-only mode,
+   * suitable for platforms like WeChat that don't support message editing).
+   *
+   * @param sealed - `true` when this is the final edit (block done streaming).
+   *   Use to switch from a "streaming" card format to a finalized one.
+   */
+  protected editBlock?(
+    channelId: string,
+    ref: TRef,
+    kind: BlockKind,
+    content: string,
+    sealed: boolean,
+  ): Promise<void>;
+
+  /**
+   * 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).
+   */
+  protected formatContent(kind: BlockKind, content: string, _sealed: boolean): string {
+    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.).
+   */
+  protected onAfterTurnEnd(_channelId: string): Promise<void> {
+    return Promise.resolve();
+  }
+
+  /**
+   * Called after a turn error, once state has been cleaned up.
+   * Override to send an error message to the user.
+   */
+  protected onAfterTurnError(_channelId: string, _error: string): Promise<void> {
+    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>"`).
+   */
+  protected sessionIdToChannelId(sessionId: string): string {
+    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: SessionNotification): void {
+    const sessionId = notification.sessionId;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const update = notification.update as any;
+    const variant = update.sessionUpdate as string;
+    const channelId = this.sessionIdToChannelId(sessionId);
+
+    switch (variant) {
+      case "agent_message_chunk": {
+        const delta = (update.content?.text ?? "") as string;
+        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 ?? "") as string;
+        if (delta) this.appendToBlock(channelId, "thinking", delta);
+        break;
+      }
+      case "tool_call": {
+        if (!this.verbose.showToolUse) return; // skip
+        const title = update.title as string | undefined;
+        if (title) this.appendToBlock(channelId, "tool", `🔧 ${title}\n`);
+        break;
+      }
+      case "tool_call_update": {
+        if (!this.verbose.showToolUse) return; // skip
+        const title = (update.title ?? "tool") as string;
+        const status = update.status as string | undefined;
+        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: string): void {
+    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: string): Promise<void> {
+    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: string, error: string): Promise<void> {
+    const state = this.states.get(channelId);
+    if (state?.flushTimer) clearTimeout(state.flushTimer);
+    this.states.delete(channelId);
+    await this.onAfterTurnError(channelId, error);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internal — block management
+  // ---------------------------------------------------------------------------
+
+  private appendToBlock(channelId: string, kind: BlockKind, delta: string): void {
+    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);
+  }
+
+  private scheduleFlush(channelId: string, state: ChannelState<TRef>): void {
+    if (state.flushTimer) return; // already scheduled
+
+    state.flushTimer = setTimeout(() => {
+      state.flushTimer = null;
+      this.flush(channelId, state);
+    }, this.flushIntervalMs);
+  }
+
+  private flush(channelId: string, state: ChannelState<TRef>): void {
+    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);
+  }
+
+  private enqueueFlush(state: ChannelState<TRef>, block: ManagedBlock<TRef>): void {
+    state.sendChain = state.sendChain
+      .then(() => this.flushBlock(state, block))
+      .catch(() => {}); // errors are handled inside flushBlock
+  }
+
+  private async flushBlock(state: ChannelState<TRef>, block: ManagedBlock<TRef>): Promise<void> {
+    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;
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,87 @@
+/**
+ * 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.
+ */
+
+// Re-export ACP SDK types so plugin authors only need one import
+export type {
+  Agent,
+  Client,
+  SessionNotification,
+  RequestPermissionRequest,
+  RequestPermissionResponse,
+} from "@agentclientprotocol/sdk";
+
+// ---------------------------------------------------------------------------
+// Plugin manifest
+// ---------------------------------------------------------------------------
+
+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;
+}
+
+// ---------------------------------------------------------------------------
+// Block rendering
+// ---------------------------------------------------------------------------
+
+/** 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>;
+}
+
+// ---------------------------------------------------------------------------
+// Init / config
+// ---------------------------------------------------------------------------
+
+/**
+ * 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;
+}