@newbase-clawchat/openclaw-clawchat 2026.4.21 → 2026.4.23

package/src/outbound.ts

@@ -1,8 +1,19 @@
 import type { ClawlingChatClient, Envelope, Fragment, MessageAckPayload } from "@newbase-clawchat/sdk";
+import {
+  createAttachedChannelResultAdapter,
+  type ChannelOutboundAdapter,
+} from "openclaw/plugin-sdk/channel-send-result";
+import { chunkMarkdownText } from "openclaw/plugin-sdk/reply-runtime";
 import type { ChatType } from "./client.ts";
-import type { ResolvedOpenclawClawlingAccount } from "./config.ts";
-import type { ClawlingMediaFragment } from "./media-runtime.ts";
+import { createOpenclawClawlingApiClient } from "./api-client.ts";
+import { CHANNEL_ID, resolveOpenclawClawlingAccount, type ResolvedOpenclawClawlingAccount } from "./config.ts";
 import { textToFragments } from "./message-mapper.ts";
+import { uploadOutboundMedia, type ClawlingMediaFragment } from "./media-runtime.ts";
+import {
+  getOpenclawClawlingClient,
+  getOpenclawClawlingRuntime,
+  waitForOpenclawClawlingClient,
+} from "./runtime.ts";
 
 export interface OutboundTarget {
   chatId: string;
@@ -37,6 +48,48 @@ export interface SendResult {
   acceptedAt: number;
 }
 
+/**
+ * Parse an agent-initiated outbound recipient string into the new-protocol
+ * `chat_id` + `chat_type` pair.
+ *
+ * Accepted forms (case-insensitive prefix):
+ *   - `cc:{chat_id}`                  → direct
+ *   - `clawchat:{chat_id}`            → direct
+ *   - `openclaw-clawchat:{chat_id}`   → direct
+ *   - `cc:direct:{chat_id}`           → direct
+ *   - `cc:group:{chat_id}`            → group
+ *   - `clawchat:direct:{chat_id}`     → direct
+ *   - `clawchat:group:{chat_id}`      → group
+ *   - `openclaw-clawchat:direct:{chat_id}` → direct
+ *   - `openclaw-clawchat:group:{chat_id}`  → group
+ *   - bare `{chat_id}`                → direct (backward compat)
+ */
+export function parseOpenclawRecipient(to: string): { chatId: string; chatType: ChatType } {
+  const raw = (to ?? "").trim();
+  if (!raw) throw new Error("openclaw-clawchat: outbound `to` is empty");
+
+  const firstColon = raw.indexOf(":");
+  if (firstColon < 0) return { chatId: raw, chatType: "direct" };
+
+  const scheme = raw.slice(0, firstColon).toLowerCase();
+  const rest = raw.slice(firstColon + 1);
+  if (scheme !== "cc" && scheme !== "clawchat" && scheme !== CHANNEL_ID) {
+    return { chatId: raw, chatType: "direct" };
+  }
+
+  const secondColon = rest.indexOf(":");
+  if (secondColon >= 0) {
+    const typeToken = rest.slice(0, secondColon).toLowerCase();
+    const chatId = rest.slice(secondColon + 1).trim();
+    if ((typeToken === "direct" || typeToken === "group") && chatId) {
+      return { chatId, chatType: typeToken };
+    }
+  }
+  const chatId = rest.trim();
+  if (!chatId) throw new Error(`openclaw-clawchat: missing chat_id in "${to}"`);
+  return { chatId, chatType: "direct" };
+}
+
 export async function sendOpenclawClawlingText(params: SendParams): Promise<SendResult | null> {
   const text = (params.text ?? "").trim();
   const mediaFragments = params.mediaFragments ?? [];
@@ -139,3 +192,63 @@ export async function sendOpenclawClawlingMedia(
     ...(params.log ? { log: params.log } : {}),
   });
 }
+
+export const openclawClawlingOutbound: ChannelOutboundAdapter = {
+  deliveryMode: "direct",
+  chunker: (text, limit) => chunkMarkdownText(text, limit),
+  chunkerMode: "markdown",
+  textChunkLimit: 4000,
+  ...createAttachedChannelResultAdapter({
+    channel: CHANNEL_ID,
+    sendText: async ({ cfg, to, text }) => {
+      const account = resolveOpenclawClawlingAccount(cfg);
+      const client =
+        getOpenclawClawlingClient(account.accountId) ??
+        (await waitForOpenclawClawlingClient(account.accountId));
+      const result = await sendOpenclawClawlingText({
+        client,
+        account,
+        to: parseOpenclawRecipient(to),
+        text,
+      });
+      return {
+        to,
+        messageId: result?.messageId ?? `${account.userId}-${Date.now()}`,
+      };
+    },
+    sendMedia: async ({ cfg, to, text, mediaUrl, mediaLocalRoots }) => {
+      const account = resolveOpenclawClawlingAccount(cfg);
+      const client =
+        getOpenclawClawlingClient(account.accountId) ??
+        (await waitForOpenclawClawlingClient(account.accountId));
+      if (!mediaUrl?.trim()) {
+        throw new Error("openclaw-clawchat sendMedia requires mediaUrl");
+      }
+      const runtime = getOpenclawClawlingRuntime();
+      const apiClient = createOpenclawClawlingApiClient({
+        baseUrl: account.baseUrl,
+        token: account.token,
+        userId: account.userId,
+      });
+      const mediaFragments = await uploadOutboundMedia([mediaUrl.trim()], {
+        apiClient,
+        runtime,
+        ...(mediaLocalRoots ? { mediaLocalRoots } : {}),
+      });
+      if (mediaFragments.length === 0) {
+        throw new Error(`openclaw-clawchat failed to upload media: ${mediaUrl}`);
+      }
+      const result = await sendOpenclawClawlingMedia({
+        client,
+        account,
+        to: parseOpenclawRecipient(to),
+        text,
+        mediaFragments,
+      });
+      return {
+        to,
+        messageId: result?.messageId ?? `${account.userId}-${Date.now()}`,
+      };
+    },
+  }),
+};

package/src/protocol.test.ts

@@ -36,7 +36,9 @@ describe("openclaw-clawchat protocol guards", () => {
 
   it("detects renderable text", () => {
     expect(hasRenderableText({ body: { fragments: [{ kind: "text", text: "hi" }] } })).toBe(true);
-    expect(hasRenderableText({ body: { fragments: [{ kind: "image", url: "x" }] } })).toBe(false);
+    expect(hasRenderableText({ body: { fragments: [{ kind: "image", url: "x" }] } })).toBe(true);
+    expect(hasRenderableText({ body: { fragments: [{ kind: "file", url: "x" }] } })).toBe(true);
     expect(hasRenderableText({ body: { fragments: [{ kind: "text", text: "  " }] } })).toBe(false);
+    expect(hasRenderableText({ body: { fragments: [{ kind: "image" }] } })).toBe(false);
   });
 });

package/src/protocol.ts

@@ -31,8 +31,12 @@ export function hasRenderableText(message: {
   const fragments = message?.body?.fragments ?? [];
   return fragments.some(
     (f) =>
-      (f as { kind?: string }).kind === "text" &&
-      typeof (f as { text?: unknown }).text === "string" &&
-      (f as { text: string }).text.trim().length > 0,
+      (((f as { kind?: string }).kind === "text" &&
+        typeof (f as { text?: unknown }).text === "string" &&
+        (f as { text: string }).text.trim().length > 0) ||
+        (typeof (f as { kind?: unknown }).kind === "string" &&
+          ["image", "file", "audio", "video"].includes((f as { kind: string }).kind) &&
+          typeof (f as { url?: unknown }).url === "string" &&
+          (f as { url: string }).url.trim().length > 0)),
   );
 }

package/src/reply-dispatcher.test.ts

@@ -0,0 +1,252 @@
+import type { ClawlingChatClient } from "@newbase-clawchat/sdk";
+import { describe, expect, it, vi } from "vitest";
+import { createOpenclawClawlingReplyDispatcher } from "./reply-dispatcher.ts";
+
+describe("openclaw-clawchat reply-dispatcher", () => {
+  it("emits message.failed in stream mode even if execution errors before any stream chunk", async () => {
+    let hooks:
+      | {
+          deliver?: (payload: { text?: string }, info?: { kind: "tool" | "block" | "final" }) => Promise<void>;
+          onIdle?: () => Promise<void>;
+          onError?: (error: unknown, info: { kind: string }) => void;
+        }
+      | undefined;
+    const sent: Array<{ event: string; payload: Record<string, unknown> }> = [];
+    const client = {
+      opts: {
+        transport: {
+          send: (data: string) => {
+            const env = JSON.parse(data) as { event: string; payload: Record<string, unknown> };
+            sent.push({ event: env.event, payload: env.payload });
+          },
+        },
+        traceIdFactory: () => "trace-1",
+      },
+      typing: vi.fn(),
+    } as unknown as ClawlingChatClient;
+
+    createOpenclawClawlingReplyDispatcher({
+      cfg: {} as never,
+      runtime: {
+        channel: {
+          reply: {
+            resolveHumanDelayConfig: vi.fn(() => ({ enabled: false })),
+            createReplyDispatcherWithTyping: vi.fn((options) => {
+              hooks = options;
+              return {
+                dispatcher: {},
+                replyOptions: {},
+                markDispatchIdle: vi.fn(),
+              };
+            }),
+          },
+        },
+      } as never,
+      account: {
+        accountId: "default",
+        userId: "agent-1",
+        replyMode: "stream",
+        forwardThinking: true,
+        forwardToolCalls: false,
+        stream: { flushIntervalMs: 250, minChunkChars: 40, maxBufferChars: 2000 },
+      } as never,
+      client,
+      target: { chatId: "chat-1", chatType: "direct" },
+      log: { info: vi.fn(), error: vi.fn() },
+    });
+
+    hooks?.onError?.(new Error("boom"), { kind: "dispatch" });
+
+    expect(sent).toHaveLength(1);
+    expect(sent[0]!.event).toBe("message.failed");
+    expect(sent[0]!.payload.reason).toBe("Error: boom");
+    expect((client.typing as ReturnType<typeof vi.fn>).mock.calls).toEqual([
+      ["chat-1", false, "direct"],
+    ]);
+  });
+
+  it("does not emit consolidated final after a streaming failure", async () => {
+    let hooks:
+      | {
+          deliver?: (payload: { text?: string }, info?: { kind: "tool" | "block" | "final" }) => Promise<void>;
+          onIdle?: () => Promise<void>;
+          onError?: (error: unknown, info: { kind: string }) => void;
+        }
+      | undefined;
+    const sent: Array<{ event: string; payload: Record<string, unknown> }> = [];
+    const client = {
+      opts: {
+        transport: {
+          send: (data: string) => {
+            const env = JSON.parse(data) as { event: string; payload: Record<string, unknown> };
+            sent.push({ event: env.event, payload: env.payload });
+          },
+        },
+        traceIdFactory: () => "trace-2",
+      },
+      typing: vi.fn(),
+    } as unknown as ClawlingChatClient;
+
+    createOpenclawClawlingReplyDispatcher({
+      cfg: {} as never,
+      runtime: {
+        channel: {
+          reply: {
+            resolveHumanDelayConfig: vi.fn(() => ({ enabled: false })),
+            createReplyDispatcherWithTyping: vi.fn((options) => {
+              hooks = options;
+              return {
+                dispatcher: {},
+                replyOptions: {},
+                markDispatchIdle: vi.fn(),
+              };
+            }),
+          },
+        },
+      } as never,
+      account: {
+        accountId: "default",
+        userId: "agent-1",
+        replyMode: "stream",
+        forwardThinking: true,
+        forwardToolCalls: false,
+        stream: { flushIntervalMs: 250, minChunkChars: 1, maxBufferChars: 2000 },
+      } as never,
+      client,
+      target: { chatId: "chat-1", chatType: "direct" },
+      inboundMessageId: "inbound-1",
+      inboundForFinalReply: {
+        senderId: "user-1",
+        senderNickName: "User 1",
+        bodyText: "hello",
+      },
+      log: { info: vi.fn(), error: vi.fn() },
+    });
+
+    await hooks?.deliver?.({ text: "partial reply" }, { kind: "block" });
+    hooks?.onError?.(new Error("boom"), { kind: "dispatch" });
+    await hooks?.onIdle?.();
+
+    expect(sent.map((entry) => entry.event)).toEqual([
+      "message.created",
+      "message.add",
+      "message.failed",
+    ]);
+    expect(sent.find((entry) => entry.event === "message.reply")).toBeUndefined();
+    expect(sent.find((entry) => entry.event === "message.done")).toBeUndefined();
+  });
+
+  it("sends static error text when non-streaming reply execution fails", async () => {
+    let hooks:
+      | {
+          onError?: (error: unknown, info: { kind: string }) => void;
+        }
+      | undefined;
+    const client = {
+      sendMessage: vi.fn().mockResolvedValue({
+        payload: { message_id: "server-m1", accepted_at: 1234 },
+      }),
+      replyMessage: vi.fn(),
+      typing: vi.fn(),
+    } as unknown as ClawlingChatClient;
+
+    createOpenclawClawlingReplyDispatcher({
+      cfg: {} as never,
+      runtime: {
+        channel: {
+          reply: {
+            resolveHumanDelayConfig: vi.fn(() => ({ enabled: false })),
+            createReplyDispatcherWithTyping: vi.fn((options) => {
+              hooks = options;
+              return {
+                dispatcher: {},
+                replyOptions: {},
+                markDispatchIdle: vi.fn(),
+              };
+            }),
+          },
+        },
+      } as never,
+      account: {
+        accountId: "default",
+        userId: "agent-1",
+        replyMode: "static",
+        forwardThinking: true,
+        forwardToolCalls: false,
+        stream: { flushIntervalMs: 250, minChunkChars: 40, maxBufferChars: 2000 },
+      } as never,
+      client,
+      target: { chatId: "chat-1", chatType: "direct" },
+      log: { info: vi.fn(), error: vi.fn() },
+    });
+
+    hooks?.onError?.(new Error("boom"), { kind: "dispatch" });
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(client.sendMessage).toHaveBeenCalledWith(
+      expect.objectContaining({
+        to: { id: "chat-1", type: "direct" },
+        body: { fragments: [{ kind: "text", text: "Error: boom" }] },
+      }),
+    );
+    expect(client.replyMessage).not.toHaveBeenCalled();
+  });
+
+  it("strips delivery retry wrapper text before sending non-streaming errors", async () => {
+    let hooks:
+      | {
+          onError?: (error: unknown, info: { kind: string }) => void;
+        }
+      | undefined;
+    const client = {
+      sendMessage: vi.fn().mockResolvedValue({
+        payload: { message_id: "server-m1", accepted_at: 1234 },
+      }),
+      replyMessage: vi.fn(),
+      typing: vi.fn(),
+    } as unknown as ClawlingChatClient;
+
+    createOpenclawClawlingReplyDispatcher({
+      cfg: {} as never,
+      runtime: {
+        channel: {
+          reply: {
+            resolveHumanDelayConfig: vi.fn(() => ({ enabled: false })),
+            createReplyDispatcherWithTyping: vi.fn((options) => {
+              hooks = options;
+              return {
+                dispatcher: {},
+                replyOptions: {},
+                markDispatchIdle: vi.fn(),
+              };
+            }),
+          },
+        },
+      } as never,
+      account: {
+        accountId: "default",
+        userId: "agent-1",
+        replyMode: "static",
+        forwardThinking: true,
+        forwardToolCalls: false,
+        stream: { flushIntervalMs: 250, minChunkChars: 40, maxBufferChars: 2000 },
+      } as never,
+      client,
+      target: { chatId: "chat-1", chatType: "direct" },
+      log: { info: vi.fn(), error: vi.fn() },
+    });
+
+    hooks?.onError?.(
+      new Error("Retry failed for delivery 123: Error: boom"),
+      { kind: "dispatch" },
+    );
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(client.sendMessage).toHaveBeenCalledWith(
+      expect.objectContaining({
+        to: { id: "chat-1", type: "direct" },
+        body: { fragments: [{ kind: "text", text: "Error: boom" }] },
+      }),
+    );
+  });
+});

package/src/reply-dispatcher.ts

@@ -13,6 +13,7 @@ import type { ResolvedOpenclawClawlingAccount } from "./config.ts";
 import { textToFragments } from "./message-mapper.ts";
 import { uploadOutboundMedia, type ClawlingMediaFragment } from "./media-runtime.ts";
 import { sendOpenclawClawlingText, type OutboundReplyCtx } from "./outbound.ts";
+import { sendStreamingFailure } from "./streaming.ts";
 
 export interface ReplyDispatcherOptions {
   cfg: OpenClawConfig;
@@ -54,6 +55,15 @@ type StreamingReplyHooks = {
   onReasoningStream?: (payload: ReplyPayload) => Promise<void>;
 };
 
+function normalizeReplyErrorText(error: unknown): string {
+  const raw = String(error);
+  const retryWrapped = raw.match(/^Error: Retry failed for delivery [^:]+:\s*(.+)$/s);
+  if (retryWrapped?.[1]?.trim()) return retryWrapped[1].trim();
+  const retryWrappedBare = raw.match(/^Retry failed for delivery [^:]+:\s*(.+)$/s);
+  if (retryWrappedBare?.[1]?.trim()) return retryWrappedBare[1].trim();
+  return raw;
+}
+
 /**
  * Reply dispatcher for openclaw-clawchat.
  *
@@ -126,6 +136,7 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
   const accumulatedMediaUrls: string[] = [];
   let finalEmitted = false;
   let streamingClosed = false;
+  let runFailed = false;
   let runDone = false;
   // `streamCreatedEmitted` is the authoritative guard: once a `message.created`
   // has been emitted for this dispatcher instance, never emit another — even
@@ -133,6 +144,9 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
   // raced the lazy open path.
   let streamCreatedEmitted = false;
 
+  const mintStreamingMessageId = () =>
+    `${account.userId}-stream-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
   const openSessionIfNeeded = () => {
     if (!streamingEnabled || streamingSession || streamCreatedEmitted) return;
     streamCreatedEmitted = true;
@@ -143,7 +157,7 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
     // which mints its own id. The inbound user message_id lives on
     // `replyTo.msgId`; keeping the two distinct avoids the agent's reply
     // frames shadowing the user turn they answer.
-    streamingMessageId = `${account.userId}-stream-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    streamingMessageId = mintStreamingMessageId();
     streamingSession = openBufferedStreamingSession({
       client,
       routing,
@@ -352,15 +366,35 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
       }
     },
     onError: (error: unknown, info: { kind: string }) => {
+      const errorText = normalizeReplyErrorText(error);
       log?.error?.(
-        `[${account.accountId}] openclaw-clawchat ${info.kind} reply failed: ${String(error)}`,
+        `[${account.accountId}] openclaw-clawchat ${info.kind} reply failed: ${errorText}`,
       );
-      void closeStreamingSession("fail", String(error));
+      if (!streamingEnabled) {
+        void sendStatic(errorText);
+        return;
+      }
+      runFailed = true;
+      if (streamingSession && !streamingClosed) {
+        void closeStreamingSession("fail", errorText);
+        return;
+      }
+      if (streamingClosed) return;
+      streamingClosed = true;
+      if (!streamingMessageId) streamingMessageId = mintStreamingMessageId();
+      void sendStreamingFailure({
+        client,
+        routing,
+        messageId: streamingMessageId,
+        currentSequence: 0,
+        reason: errorText,
+      });
     },
     onIdle: async () => {
       if (runDone) return;
       runDone = true;
       if (!streamingEnabled) return;
+      if (runFailed) return;
       await closeStreamingSession("done");
       await emitFinalConsolidatedMessage();
     },