@vibearound/plugin-channel-sdk 0.1.2 → 0.4.0

package/src/renderer.ts

@@ -25,36 +25,68 @@
  *
  * ## Usage
  *
+ * Subclass and implement `sendText` + `sendBlock` (+ optionally `editBlock`):
+ *
  * ```ts
  * class MyRenderer extends BlockRenderer<string> {
- *   protected async sendBlock(channelId, kind, content) {
- *     const msg = await myApi.sendMessage(channelId, content);
+ *   protected async sendText(chatId, text) {
+ *     await myApi.sendMessage(chatId, text);
+ *   }
+ *   protected async sendBlock(chatId, kind, content) {
+ *     const msg = await myApi.sendMessage(chatId, content);
  *     return msg.id;
  *   }
- *   protected async editBlock(channelId, ref, kind, content, sealed) {
+ *   protected async editBlock(chatId, 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);
  * ```
+ *
+ * The SDK's `runChannelPlugin` wires all ACP events to this renderer
+ * automatically — plugins don't call onSessionUpdate/onPromptSent/etc
+ * directly.
  */
 
 import type { SessionNotification } from "@agentclientprotocol/sdk";
-import type { BlockKind, BlockRendererOptions, VerboseConfig } from "./types.js";
+import type { BlockKind, BlockRendererOptions, CommandEntry, VerboseConfig } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Local ACP session-update narrowing
+// ---------------------------------------------------------------------------
+//
+// The ACP SDK's `SessionNotification.update` is a discriminated union keyed on
+// the `sessionUpdate` field, but the shape we get back at runtime varies by
+// version. We only consume four variants here, so we define a narrow local
+// view that documents exactly the fields this renderer depends on. A mismatch
+// against the upstream type will show up as a compile error when the SDK is
+// bumped, instead of silently producing `undefined` at runtime.
+
+interface AgentMessageChunk {
+  sessionUpdate: "agent_message_chunk";
+  content?: { text?: string };
+}
+
+interface AgentThoughtChunk {
+  sessionUpdate: "agent_thought_chunk";
+  content?: { text?: string };
+}
+
+interface ToolCall {
+  sessionUpdate: "tool_call";
+  title?: string;
+}
+
+interface ToolCallUpdate {
+  sessionUpdate: "tool_call_update";
+  title?: string;
+  status?: string;
+}
+
+type ConsumedSessionUpdate =
+  | AgentMessageChunk
+  | AgentThoughtChunk
+  | ToolCall
+  | ToolCallUpdate;
 
 // ---------------------------------------------------------------------------
 // Internal state types
@@ -62,7 +94,7 @@ import type { BlockKind, BlockRendererOptions, VerboseConfig } from "./types.js"
 
 interface ManagedBlock<TRef> {
   /** Channel this block belongs to. Captured at creation time. */
-  channelId: string;
+  chatId: string;
   kind: BlockKind;
   content: string;
   /** Platform message reference set after the first successful send. */
@@ -101,13 +133,21 @@ const DEFAULT_MIN_EDIT_INTERVAL_MS = 1000;
  *   return type of `sendBlock` and the first argument of `editBlock`.
  */
 export abstract class BlockRenderer<TRef = string> {
+  /** When true, blocks are sent and edited in real-time. When false, each
+   *  block is held until complete, then sent once (send-only mode). */
+  protected readonly streaming: boolean;
   protected readonly flushIntervalMs: number;
   protected readonly minEditIntervalMs: number;
   protected readonly verbose: VerboseConfig;
 
   private states = new Map<string, ChannelState<TRef>>();
 
+  /** The chatId of the most recent prompt. Used as fallback target for
+   *  notifications that arrive without an explicit chatId. */
+  private lastActiveChatId: string | null = null;
+
   constructor(options: BlockRendererOptions = {}) {
+    this.streaming = options.streaming ?? true;
     this.flushIntervalMs = options.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS;
     this.minEditIntervalMs = options.minEditIntervalMs ?? DEFAULT_MIN_EDIT_INTERVAL_MS;
     this.verbose = {
@@ -117,21 +157,31 @@ export abstract class BlockRenderer<TRef = string> {
   }
 
   // ---------------------------------------------------------------------------
-  // Abstract / overridable — subclass implements these
+  // Abstract — plugin MUST implement these
   // ---------------------------------------------------------------------------
 
   /**
-   * Send a new block message to the platform.
+   * Send a plain text message to the IM. Used for system text, agent ready
+   * notifications, session ready, and error messages.
+   */
+  protected abstract sendText(chatId: string, text: string): Promise<void>;
+
+  /**
+   * Send a new streaming 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,
+    chatId: string,
     kind: BlockKind,
     content: string,
   ): Promise<TRef | null>;
 
+  // ---------------------------------------------------------------------------
+  // Optional overrides — plugin MAY implement these
+  // ---------------------------------------------------------------------------
+
   /**
    * Edit an existing block message in-place.
    *
@@ -142,7 +192,7 @@ export abstract class BlockRenderer<TRef = string> {
    *   Use to switch from a "streaming" card format to a finalized one.
    */
   protected editBlock?(
-    channelId: string,
+    chatId: string,
     ref: TRef,
     kind: BlockKind,
     content: string,
@@ -169,31 +219,18 @@ export abstract class BlockRenderer<TRef = string> {
 
   /**
    * 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.
+   * Override to perform cleanup (e.g. remove a "typing" indicator).
    */
-  protected onAfterTurnError(_channelId: string, _error: string): Promise<void> {
+  protected onAfterTurnEnd(_chatId: 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>"`).
+   * Called after a turn error. Default sends an error message via sendText.
+   * Override for platform-specific error rendering (e.g. error card).
    */
-  protected sessionIdToChannelId(sessionId: string): string {
-    return sessionId;
+  protected async onAfterTurnError(chatId: string, error: string): Promise<void> {
+    await this.sendText(chatId, `❌ Error: ${error}`);
   }
 
   // ---------------------------------------------------------------------------
@@ -206,39 +243,46 @@ export abstract class BlockRenderer<TRef = string> {
    * 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.
+   * Called automatically by `runChannelPlugin` — plugins don't call this directly.
    */
   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);
+    // sessionId from ACP = chatId (the host replaces the real agent session
+    // ID with the chat ID before forwarding to the plugin).
+    const chatId = notification.sessionId;
+    const rawUpdate = notification.update as unknown as { sessionUpdate: string };
+    const variant = rawUpdate.sessionUpdate;
+    if (
+      variant !== "agent_message_chunk" &&
+      variant !== "agent_thought_chunk" &&
+      variant !== "tool_call" &&
+      variant !== "tool_call_update"
+    ) {
+      return;
+    }
+    const update = rawUpdate as ConsumedSessionUpdate;
 
-    switch (variant) {
+    switch (update.sessionUpdate) {
       case "agent_message_chunk": {
-        const delta = (update.content?.text ?? "") as string;
-        if (delta) this.appendToBlock(channelId, "text", delta);
+        const delta = update.content?.text ?? "";
+        if (delta) this.appendToBlock(chatId, "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);
+        if (!this.verbose.showThinking) return;
+        const delta = update.content?.text ?? "";
+        if (delta) this.appendToBlock(chatId, "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`);
+        if (!this.verbose.showToolUse) return;
+        if (update.title) this.appendToBlock(chatId, "tool", `🔧 ${update.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`);
+        if (!this.verbose.showToolUse) return;
+        const title = update.title ?? "tool";
+        if (update.status === "completed" || update.status === "error") {
+          this.appendToBlock(chatId, "tool", `✅ ${title}\n`);
         }
         break;
       }
@@ -246,15 +290,14 @@ export abstract class BlockRenderer<TRef = string> {
   }
 
   /**
-   * 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.
+   * Call before sending a prompt. Tracks the active chatId and clears
+   * leftover state from a previous turn.
    */
-  onPromptSent(channelId: string): void {
-    const old = this.states.get(channelId);
+  onPromptSent(chatId: string): void {
+    this.lastActiveChatId = chatId;
+    const old = this.states.get(chatId);
     if (old?.flushTimer) clearTimeout(old.flushTimer);
-    this.states.set(channelId, {
+    this.states.set(chatId, {
       blocks: [],
       flushTimer: null,
       lastEditMs: 0,
@@ -262,14 +305,70 @@ export abstract class BlockRenderer<TRef = string> {
     });
   }
 
+  // ---------------------------------------------------------------------------
+  // Host notification handlers — built-in defaults, no per-plugin duplication
+  // ---------------------------------------------------------------------------
+
+  /** Handle `va/system_text` from host. */
+  onSystemText(chatId: string, text: string): void {
+    this.sendText(chatId, text).catch(() => {});
+  }
+
+  /** Handle `va/agent_ready` from host. */
+  onAgentReady(chatId: string, agent: string, version: string): void {
+    this.sendText(chatId, `🤖 Agent: ${agent} v${version}`).catch(() => {});
+  }
+
+  /** Handle `va/session_ready` from host. */
+  onSessionReady(chatId: string, sessionId: string): void {
+    this.sendText(chatId, `📋 Session: ${sessionId}`).catch(() => {});
+  }
+
+  /**
+   * Handle `va/command_menu` from host — display available commands.
+   *
+   * Default renders a plain-text list. Override for platform-specific
+   * rendering (e.g. Feishu interactive card, Slack Block Kit, Telegram
+   * inline keyboard).
+   */
+  onCommandMenu(
+    chatId: string,
+    systemCommands: CommandEntry[],
+    agentCommands: CommandEntry[],
+  ): void {
+    const lines: string[] = [];
+
+    lines.push("System commands:");
+    for (const cmd of systemCommands) {
+      const usage = cmd.args ? `/${cmd.name} ${cmd.args}` : `/${cmd.name}`;
+      lines.push(`  ${usage} — ${cmd.description}`);
+    }
+
+    if (agentCommands.length > 0) {
+      lines.push("");
+      lines.push("Agent commands (use /agent <command>):");
+      for (const cmd of agentCommands) {
+        const desc = cmd.description.length > 80
+          ? `${cmd.description.slice(0, 77)}...`
+          : cmd.description;
+        lines.push(`  /${cmd.name} — ${desc}`);
+      }
+    } else {
+      lines.push("");
+      lines.push("Agent commands will appear after sending your first message.");
+    }
+
+    this.sendText(chatId, lines.join("\n")).catch(() => {});
+  }
+
   /**
    * 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);
+  async onTurnEnd(chatId: string): Promise<void> {
+    const state = this.states.get(chatId);
     if (!state) return;
 
     if (state.flushTimer) {
@@ -283,35 +382,33 @@ export abstract class BlockRenderer<TRef = string> {
       this.enqueueFlush(state, last);
     }
 
-    // Wait for the entire chain to drain before cleanup
     await state.sendChain;
-    this.states.delete(channelId);
-    await this.onAfterTurnEnd(channelId);
+    this.states.delete(chatId);
+    await this.onAfterTurnEnd(chatId);
   }
 
   /**
    * 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.
+   * Discards pending state and calls `onAfterTurnError`.
    */
-  async onTurnError(channelId: string, error: string): Promise<void> {
-    const state = this.states.get(channelId);
+  async onTurnError(chatId: string, error: string): Promise<void> {
+    const state = this.states.get(chatId);
     if (state?.flushTimer) clearTimeout(state.flushTimer);
-    this.states.delete(channelId);
-    await this.onAfterTurnError(channelId, error);
+    this.states.delete(chatId);
+    await this.onAfterTurnError(chatId, error);
   }
 
   // ---------------------------------------------------------------------------
   // Internal — block management
   // ---------------------------------------------------------------------------
 
-  private appendToBlock(channelId: string, kind: BlockKind, delta: string): void {
-    let state = this.states.get(channelId);
+  private appendToBlock(chatId: string, kind: BlockKind, delta: string): void {
+    let state = this.states.get(chatId);
     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);
+      this.states.set(chatId, state);
     }
 
     const last = state.blocks.at(-1);
@@ -330,25 +427,33 @@ export abstract class BlockRenderer<TRef = string> {
         }
         this.enqueueFlush(state, last);
       }
-      state.blocks.push({ channelId, kind, content: delta, ref: null, creating: false, sealed: false });
+      state.blocks.push({ chatId, kind, content: delta, ref: null, creating: false, sealed: false });
     }
 
-    this.scheduleFlush(channelId, state);
+    this.scheduleFlush(chatId, state);
   }
 
-  private scheduleFlush(channelId: string, state: ChannelState<TRef>): void {
+  private scheduleFlush(chatId: string, state: ChannelState<TRef>): void {
     if (state.flushTimer) return; // already scheduled
 
     state.flushTimer = setTimeout(() => {
       state.flushTimer = null;
-      this.flush(channelId, state);
+      this.flush(chatId, state);
     }, this.flushIntervalMs);
   }
 
-  private flush(channelId: string, state: ChannelState<TRef>): void {
+  private flush(chatId: string, state: ChannelState<TRef>): void {
     const block = state.blocks.at(-1);
     if (!block || block.sealed || !block.content) return;
 
+    // Send-only mode (streaming=false): defer intermediate sends.
+    // Only sealed blocks (from onTurnEnd or block boundary transitions)
+    // will actually POST. This prevents the user seeing a partial chunk
+    // followed by the full message as two separate messages.
+    if (!this.streaming) {
+      return;
+    }
+
     const now = Date.now();
     if (now - state.lastEditMs < this.minEditIntervalMs) {
       // Throttled — reschedule for the remaining window
@@ -356,7 +461,7 @@ export abstract class BlockRenderer<TRef = string> {
       if (!state.flushTimer) {
         state.flushTimer = setTimeout(() => {
           state.flushTimer = null;
-          this.flush(channelId, state);
+          this.flush(chatId, state);
         }, delay);
       }
       return;
@@ -379,12 +484,12 @@ export abstract class BlockRenderer<TRef = string> {
       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.ref = await this.sendBlock(block.chatId, 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);
+      } else if (block.ref !== null && !block.creating && this.streaming && this.editBlock) {
+        // Subsequent update — edit in-place (streaming mode only)
+        await this.editBlock(block.chatId, block.ref, block.kind, content, block.sealed);
         state.lastEditMs = Date.now();
       }
       // else: create is in-flight (creating === true) — skip

package/src/types.ts

@@ -43,6 +43,18 @@ export interface PluginManifest {
   capabilities?: PluginCapabilities;
 }
 
+// ---------------------------------------------------------------------------
+// Command menu
+// ---------------------------------------------------------------------------
+
+/** A command entry from the host's command list. */
+export interface CommandEntry {
+  name: string;
+  description: string;
+  args?: string;
+  aliases?: string[];
+}
+
 // ---------------------------------------------------------------------------
 // Block rendering
 // ---------------------------------------------------------------------------
@@ -58,6 +70,18 @@ export interface VerboseConfig {
 }
 
 export interface BlockRendererOptions {
+  /**
+   * Whether the IM platform supports message editing (streaming mode).
+   *
+   * - `true` (default): blocks stream in real-time — `sendBlock()` creates
+   *   the message, `editBlock()` updates it as more content arrives.
+   * - `false`: each block is held until complete, then sent once via
+   *   `sendBlock()`. `editBlock()` is never called.
+   *
+   * Set to `false` for platforms that don't support editing sent messages
+   * (e.g. QQ Bot, WhatsApp, WeChat, LINE).
+   */
+  streaming?: boolean;
   /**
    * Debounce interval before flushing an unsealed block (ms).
    * Controls how often in-progress blocks are sent to the platform.