@newbase-clawchat/openclaw-clawchat 2026.4.15

package/src/runtime.test.ts

@@ -0,0 +1,276 @@
+import { MockTransport, AuthError } from "@newbase-clawchat/sdk";
+import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk/core";
+import { describe, expect, it, vi } from "vitest";
+import {
+  classifyClawlingClientError,
+  mapClawlingStateToStatus,
+  setOpenclawClawlingRuntime,
+  getOpenclawClawlingRuntime,
+} from "./runtime.ts";
+
+describe("openclaw-clawchat runtime helpers", () => {
+  it("maps SDK states to channel status shape", () => {
+    expect(mapClawlingStateToStatus("connected")).toMatchObject({
+      connected: true,
+      running: true,
+    });
+    expect(mapClawlingStateToStatus("reconnecting")).toMatchObject({
+      connected: false,
+      running: true,
+    });
+    expect(mapClawlingStateToStatus("disconnected")).toMatchObject({
+      connected: false,
+      running: false,
+    });
+    expect(mapClawlingStateToStatus("connecting")).toMatchObject({
+      connected: false,
+      running: true,
+    });
+  });
+
+  it("classifies AuthError as fatal/no-retry", () => {
+    const c = classifyClawlingClientError(new AuthError("hello-fail", "bad-token"));
+    expect(c.kind).toBe("auth");
+    expect(c.retry).toBe(false);
+  });
+
+  it("classifies generic errors as unknown", () => {
+    const c = classifyClawlingClientError(new Error("huh"));
+    expect(c.kind).toBe("unknown");
+    expect(c.retry).toBe(false);
+  });
+
+  it("runtime store round-trips", () => {
+    const rt = { mocked: true } as unknown as PluginRuntime;
+    setOpenclawClawlingRuntime(rt);
+    expect(getOpenclawClawlingRuntime()).toBe(rt);
+  });
+});
+
+describe("openclaw-clawchat runtime media ingest", () => {
+  it("fetches inbound media via runtime.channel.media and populates MediaPath/MediaPaths", async () => {
+    const fetched: Array<{ url: string }> = [];
+    const saved: Array<{ ct: string | undefined }> = [];
+    let capturedCtx: Record<string, unknown> | undefined;
+    const finalizeInboundContext = vi.fn((ctx: Record<string, unknown>) => {
+      capturedCtx = ctx;
+      return ctx;
+    });
+
+    const runtime = {
+      channel: {
+        routing: {
+          resolveAgentRoute: vi.fn(() => ({
+            agentId: "u",
+            accountId: "default",
+            sessionKey: "s",
+          })),
+        },
+        session: {
+          resolveStorePath: vi.fn(() => "/tmp/sessions.json"),
+          recordInboundSession: vi.fn().mockResolvedValue(undefined),
+        },
+        reply: {
+          formatAgentEnvelope: vi.fn((p: { body: string }) => p.body),
+          resolveEnvelopeFormatOptions: vi.fn(() => ({})),
+          finalizeInboundContext,
+          resolveHumanDelayConfig: vi.fn(() => ({ enabled: false })),
+          createReplyDispatcherWithTyping: vi.fn(() => ({
+            dispatcher: {},
+            replyOptions: {},
+            markDispatchIdle: vi.fn(),
+            markRunComplete: vi.fn(),
+          })),
+          withReplyDispatcher: vi.fn(async (opts: { run: () => Promise<unknown> }) => {
+            await opts.run();
+          }),
+          dispatchReplyFromConfig: vi.fn().mockResolvedValue(undefined),
+        },
+        media: {
+          fetchRemoteMedia: vi.fn(async ({ url }: { url: string }) => {
+            fetched.push({ url });
+            return { buffer: Buffer.from("x"), contentType: "image/png", fileName: "f.png" };
+          }),
+          saveMediaBuffer: vi.fn(async (_buf, ct?: string) => {
+            saved.push({ ct });
+            return { path: `/cache/${saved.length}.png`, contentType: "image/png" };
+          }),
+          loadWebMedia: vi.fn(),
+        },
+      },
+    } as unknown as import("openclaw/plugin-sdk/core").PluginRuntime;
+
+    setOpenclawClawlingRuntime(runtime);
+
+    const { startOpenclawClawlingGateway } = await import("./runtime.ts");
+    const { MockTransport } = await import("@newbase-clawchat/sdk");
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    const startPromise = startOpenclawClawlingGateway({
+      cfg: {} as import("openclaw/plugin-sdk/core").OpenClawConfig,
+      account: {
+        accountId: "default",
+        name: "openclaw-clawchat",
+        enabled: true,
+        configured: true,
+        websocketUrl: "ws://t",
+        baseUrl: "https://api.example.com",
+        token: "tk",
+        userId: "u",
+        replyMode: "static",
+        forwardThinking: true,
+        forwardToolCalls: false,
+        allowFrom: [],
+        stream: { flushIntervalMs: 250, minChunkChars: 40, maxBufferChars: 2000 },
+        reconnect: {
+          initialDelay: 1000,
+          maxDelay: 30000,
+          jitterRatio: 0.3,
+          maxRetries: Number.POSITIVE_INFINITY,
+        },
+        heartbeat: { interval: 25000, timeout: 10000 },
+        ack: { timeout: 10000, autoResendOnTimeout: false },
+      },
+      abortSignal: abortController.signal,
+      setStatus: vi.fn(),
+      getStatus: vi.fn(() => ({ accountId: "default" })),
+      log: { info: () => {}, error: () => {} },
+      transport,
+    });
+
+    await new Promise((r) => setTimeout(r, 0));
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "connect.challenge",
+        trace_id: "tc",
+        emitted_at: Date.now(),
+        payload: { nonce: "n" },
+      }),
+    );
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "hello-ok",
+        trace_id: "th",
+        emitted_at: Date.now(),
+        payload: {},
+      }),
+    );
+    await new Promise((r) => setTimeout(r, 5));
+
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "message.send",
+        trace_id: "ti",
+        emitted_at: Date.now(),
+        to: { id: "u", type: "direct" },
+        sender: { sender_id: "user-1", type: "direct", display_name: "User" },
+        payload: {
+          message_id: "m-with-image",
+          message_mode: "normal",
+          message: {
+            body: {
+              fragments: [
+                { kind: "text", text: "see this:" },
+                { kind: "image", url: "https://cdn/a.png", mime: "image/png" },
+              ],
+            },
+            context: { mentions: [], reply: null },
+            streaming: {
+              status: "static",
+              sequence: 0,
+              mutation_policy: "sealed",
+              started_at: null,
+              completed_at: null,
+            },
+            sender: { sender_id: "user-1", type: "direct", display_name: "User" },
+          },
+        },
+      }),
+    );
+    await new Promise((r) => setTimeout(r, 30));
+    abortController.abort();
+    await startPromise;
+
+    expect(fetched).toEqual([{ url: "https://cdn/a.png" }]);
+    expect(capturedCtx?.MediaPath).toBe("/cache/1.png");
+    expect(capturedCtx?.MediaPaths).toEqual(["/cache/1.png"]);
+  });
+});
+
+describe("openclaw-clawchat runtime connect flow", () => {
+  it("completes connect through MockTransport handshake", async () => {
+    const { startOpenclawClawlingGateway } = await import("./runtime.ts");
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+    const setStatus = vi.fn();
+    const getStatus = vi.fn(() => ({ accountId: "default" }));
+
+    // Provide a stub PluginRuntime so getOpenclawClawlingRuntime() resolves inside the gateway.
+    setOpenclawClawlingRuntime({ channel: undefined } as unknown as PluginRuntime);
+
+    const startPromise = startOpenclawClawlingGateway({
+      cfg: {} as OpenClawConfig,
+      account: {
+        accountId: "default",
+        name: "openclaw-clawchat",
+        enabled: true,
+        configured: true,
+        websocketUrl: "ws://t",
+        baseUrl: "",
+        token: "tk",
+        userId: "agent-1",
+        replyMode: "static",
+        forwardThinking: true,
+        forwardToolCalls: false,
+        allowFrom: [],
+        stream: { flushIntervalMs: 250, minChunkChars: 40, maxBufferChars: 2000 },
+        reconnect: {
+          initialDelay: 1000,
+          maxDelay: 30000,
+          jitterRatio: 0.3,
+          maxRetries: Number.POSITIVE_INFINITY,
+        },
+        heartbeat: { interval: 25000, timeout: 10000 },
+        ack: { timeout: 10000, autoResendOnTimeout: false },
+      },
+      abortSignal: abortController.signal,
+      setStatus,
+      getStatus,
+      log: { info: () => {}, error: () => {} },
+      transport,
+    });
+
+    // Give event loop one tick so connect() subscribes, then authenticate.
+    await new Promise((r) => setTimeout(r, 0));
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "connect.challenge",
+        trace_id: "t1",
+        emitted_at: Date.now(),
+        payload: { nonce: "n1" },
+      }),
+    );
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "hello-ok",
+        trace_id: "t2",
+        emitted_at: Date.now(),
+        payload: {},
+      }),
+    );
+    // Let the state propagate, then abort so startOpenclawClawlingGateway resolves.
+    await new Promise((r) => setTimeout(r, 10));
+    abortController.abort();
+    await startPromise;
+
+    expect(setStatus).toHaveBeenCalledWith(
+      expect.objectContaining({ connected: true, running: true }),
+    );
+  });
+});

package/src/runtime.ts

@@ -0,0 +1,316 @@
+import {
+  AckTimeoutError,
+  AuthError,
+  ProtocolError,
+  StateError,
+  TransportError,
+  type ClawlingChatClient,
+  type DownlinkMessageSendPayload,
+  type Envelope,
+  type Transport,
+} from "@newbase-clawchat/sdk";
+import type { ChannelAccountSnapshot } from "openclaw/plugin-sdk/channel-contract";
+import { waitUntilAbort } from "openclaw/plugin-sdk/channel-lifecycle";
+import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk/core";
+import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
+import { createOpenclawClawlingClient } from "./client.ts";
+import { CHANNEL_ID, type ResolvedOpenclawClawlingAccount } from "./config.ts";
+import { dispatchOpenclawClawlingInbound } from "./inbound.ts";
+import { fetchInboundMedia } from "./media-runtime.ts";
+import { createOpenclawClawlingReplyDispatcher } from "./reply-dispatcher.ts";
+import { sendStreamingText } from "./streaming.ts";
+
+type Log = { info?: (m: string) => void; error?: (m: string) => void };
+
+const { setRuntime: setOpenclawClawlingRuntime, getRuntime: getOpenclawClawlingRuntime } =
+  createPluginRuntimeStore<PluginRuntime>("openclaw-clawchat runtime not initialized");
+
+export { setOpenclawClawlingRuntime, getOpenclawClawlingRuntime };
+
+const activeClients = new Map<string, ClawlingChatClient>();
+
+export function getOpenclawClawlingClient(accountId: string): ClawlingChatClient | undefined {
+  return activeClients.get(accountId);
+}
+
+export type ClawlingState =
+  | "idle"
+  | "connecting"
+  | "challenging"
+  | "authenticating"
+  | "connected"
+  | "reconnecting"
+  | "disconnected";
+
+export function mapClawlingStateToStatus(state: ClawlingState): {
+  connected: boolean;
+  running: boolean;
+  lastStartAt?: number;
+  lastStopAt?: number;
+} {
+  const now = Date.now();
+  switch (state) {
+    case "connected":
+      return { connected: true, running: true, lastStartAt: now };
+    case "reconnecting":
+      return { connected: false, running: true };
+    case "disconnected":
+      return { connected: false, running: false, lastStopAt: now };
+    default:
+      return { connected: false, running: true };
+  }
+}
+
+export function classifyClawlingClientError(err: unknown): {
+  kind: "auth" | "transport" | "protocol" | "ack-timeout" | "state" | "unknown";
+  retry: boolean;
+  message: string;
+} {
+  if (err instanceof AuthError) return { kind: "auth", retry: false, message: err.message };
+  if (err instanceof TransportError)
+    return { kind: "transport", retry: true, message: err.message };
+  if (err instanceof AckTimeoutError)
+    return { kind: "ack-timeout", retry: false, message: err.message };
+  if (err instanceof ProtocolError) return { kind: "protocol", retry: false, message: err.message };
+  if (err instanceof StateError) return { kind: "state", retry: false, message: err.message };
+  return {
+    kind: "unknown",
+    retry: false,
+    message: err instanceof Error ? err.message : String(err),
+  };
+}
+
+export interface StartGatewayParams {
+  cfg: OpenClawConfig;
+  account: ResolvedOpenclawClawlingAccount;
+  abortSignal: AbortSignal;
+  setStatus: (next: ChannelAccountSnapshot) => void;
+  getStatus: () => ChannelAccountSnapshot;
+  log?: Log;
+  /** Test hook only. */
+  transport?: Transport;
+}
+
+export async function startOpenclawClawlingGateway(params: StartGatewayParams): Promise<void> {
+  const { cfg, account, abortSignal, setStatus, getStatus, log } = params;
+  // Obtain PluginRuntime from the stored runtime set via setOpenclawClawlingRuntime.
+  const runtime = getOpenclawClawlingRuntime();
+  const accountId = account.accountId;
+
+  const client = createOpenclawClawlingClient(account, {
+    ...(params.transport ? { transport: params.transport } : {}),
+  });
+
+  client.on("state", ({ from, to }) => {
+    log?.info?.(`[${accountId}] openclaw-clawchat state ${from} -> ${to}`);
+    const next = { ...getStatus(), ...mapClawlingStateToStatus(to as ClawlingState) };
+    setStatus(next);
+  });
+
+  client.on("error", (err: unknown) => {
+    const classified = classifyClawlingClientError(err);
+    if (classified.kind === "auth") {
+      log?.error?.(`[${accountId}] openclaw-clawchat auth failed: ${classified.message}`);
+      setStatus({
+        ...getStatus(),
+        connected: false,
+        configured: false,
+        running: false,
+        lastError: classified.message,
+      });
+    } else if (classified.kind === "transport") {
+      log?.info?.(
+        `[${accountId}] openclaw-clawchat transport error (reconnecting): ${classified.message}`,
+      );
+      setStatus({ ...getStatus(), connected: false, running: true });
+    } else if (classified.kind === "ack-timeout") {
+      log?.info?.(`[${accountId}] openclaw-clawchat ack timeout: ${classified.message}`);
+    } else if (classified.kind === "protocol") {
+      log?.error?.(`[${accountId}] openclaw-clawchat protocol error: ${classified.message}`);
+    } else if (classified.kind === "state") {
+      log?.info?.(`[${accountId}] openclaw-clawchat state error: ${classified.message}`);
+    } else {
+      log?.error?.(`[${accountId}] openclaw-clawchat sdk error: ${classified.message}`);
+    }
+  });
+
+  client.on("message", (env: Envelope) => {
+    dispatchOpenclawClawlingInbound({
+      envelope: env as Envelope<DownlinkMessageSendPayload>,
+      cfg,
+      runtime,
+      account,
+      log,
+      ingest: async (turn) => {
+        const rt = runtime.channel;
+        const storePath = rt.session.resolveStorePath(cfg.session?.store);
+        const route = rt.routing.resolveAgentRoute({
+          cfg,
+          channel: CHANNEL_ID,
+          accountId,
+          peer: turn.peer,
+        });
+        const body = rt.reply.formatAgentEnvelope({
+          channel: "Clawling Chat",
+          from: turn.senderNickName || turn.senderId,
+          body: turn.rawBody,
+          timestamp: turn.timestamp,
+          ...rt.reply.resolveEnvelopeFormatOptions(cfg),
+        });
+        const ctxPayload = rt.reply.finalizeInboundContext({
+          Body: body,
+          BodyForAgent: turn.rawBody,
+          RawBody: turn.rawBody,
+          CommandBody: turn.rawBody,
+          From: `${CHANNEL_ID}:${turn.senderId}`,
+          To: `${CHANNEL_ID}:${account.userId}`,
+          SessionKey: route.sessionKey,
+          AccountId: route.accountId ?? accountId,
+          ChatType: turn.peer.kind,
+          ConversationLabel: turn.senderNickName || turn.senderId,
+          SenderId: turn.senderId,
+          Provider: CHANNEL_ID,
+          Surface: CHANNEL_ID,
+          MessageSid: turn.messageId,
+          MessageSidFull: turn.messageId,
+          Timestamp: turn.timestamp,
+          OriginatingChannel: CHANNEL_ID,
+          OriginatingTo: `${CHANNEL_ID}:${account.userId}`,
+        });
+        // Fetch any inbound media attachments and populate MediaPath/MediaPaths in context.
+        const inboundPaths =
+          turn.mediaItems.length > 0
+            ? await fetchInboundMedia(turn.mediaItems, {
+                runtime,
+                log,
+                maxBytes: 20 * 1024 * 1024,
+              })
+            : [];
+        if (inboundPaths.length > 0) {
+          (ctxPayload as Record<string, unknown>).MediaPath = inboundPaths[0];
+          (ctxPayload as Record<string, unknown>).MediaPaths = inboundPaths;
+        }
+
+        try {
+          await rt.session.recordInboundSession({
+            storePath,
+            sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+            ctx: ctxPayload,
+            onRecordError: (err) => {
+              log?.error?.(
+                `[${accountId}] openclaw-clawchat failed to record inbound session: ${String(err)}`,
+              );
+            },
+          });
+        } catch (err) {
+          log?.error?.(
+            `[${accountId}] openclaw-clawchat failed to record inbound session: ${String(err)}`,
+          );
+        }
+
+        const replyCtx = turn.replyCtx;
+        const { dispatcher, replyOptions, markDispatchIdle } =
+          createOpenclawClawlingReplyDispatcher({
+            cfg,
+            runtime,
+            account,
+            client,
+            target: { chatId: turn.peer.id, chatType: turn.peer.kind },
+            ...(replyCtx ? { replyCtx } : {}),
+            inboundMessageId: turn.messageId,
+            inboundForFinalReply: {
+              senderId: turn.senderId,
+              senderNickName: turn.senderNickName || turn.senderId,
+              bodyText: turn.rawBody,
+            },
+            log,
+          });
+
+        const agentsConfigured = Object.keys((cfg as { agents?: Record<string, unknown> }).agents ?? {});
+        log?.info?.(
+          `[${accountId}] openclaw-clawchat dispatching reply msg=${turn.messageId} session=${ctxPayload.SessionKey ?? route.sessionKey} agent=${route.agentId} agentsConfigured=[${agentsConfigured.join(",")}]`,
+        );
+        try {
+          const dispatchResult = await rt.reply.withReplyDispatcher({
+            dispatcher,
+            run: () =>
+              rt.reply.dispatchReplyFromConfig({ ctx: ctxPayload, cfg, dispatcher, replyOptions }),
+          });
+          const counts = (dispatchResult as { counts?: Record<string, number> } | undefined)?.counts ?? {};
+          const queuedFinal = Boolean(
+            (dispatchResult as { queuedFinal?: boolean } | undefined)?.queuedFinal,
+          );
+          log?.info?.(
+            `[${accountId}] openclaw-clawchat dispatch complete msg=${turn.messageId} queuedFinal=${queuedFinal} counts=${JSON.stringify(counts)}`,
+          );
+          if (!queuedFinal && Object.values(counts).every((n) => !n)) {
+            log?.info?.(
+              `[${accountId}] openclaw-clawchat NO reply was produced (no final / block / tool dispatched). ` +
+                `Likely causes: agent='${route.agentId}' not configured in cfg.agents (configured: [${agentsConfigured.join(",")}]); ` +
+                `or send-policy denied; or a plugin claimed the binding.`,
+            );
+          }
+        } catch (err) {
+          log?.error?.(
+            `[${accountId}] openclaw-clawchat dispatch failed msg=${turn.messageId}: ${String(err)}`,
+          );
+          throw err;
+        } finally {
+          markDispatchIdle();
+        }
+      },
+    }).catch((err) => {
+      log?.error?.(
+        `[${accountId}] openclaw-clawchat inbound dispatch error: ${err instanceof Error ? err.stack || err.message : String(err)}`,
+      );
+    });
+  });
+
+  // `client.connect()` resolves on `hello-ok` or rejects on `hello-fail`
+  // (auth). Transport failures (server unreachable, DNS error, etc.) do
+  // NOT reject this promise — the SDK catches them internally and drives
+  // its own exponential-backoff reconnect loop (`initialDelay * 2^attempt`
+  // capped at `maxDelay`, with jitter). So we never throw here on anything
+  // other than auth failure; on auth we tear the account down cleanly and
+  // return without throwing (which would make the gateway supervisor
+  // restart us immediately in a tight loop).
+  try {
+    await client.connect();
+  } catch (err) {
+    const classified = classifyClawlingClientError(err);
+    setStatus({
+      ...getStatus(),
+      connected: false,
+      configured: classified.kind !== "auth",
+      running: false,
+      lastError: classified.message,
+    });
+    log?.error?.(
+      `[${accountId}] openclaw-clawchat connect failed (${classified.kind}): ${classified.message}`,
+    );
+    return;
+  }
+  activeClients.set(accountId, client);
+  setStatus({
+    ...getStatus(),
+    connected: true,
+    running: true,
+    lastStartAt: Date.now(),
+  });
+  log?.info?.(`[${accountId}] openclaw-clawchat connected`);
+
+  await waitUntilAbort(abortSignal, async () => {
+    activeClients.delete(accountId);
+    client.close();
+    setStatus({
+      ...getStatus(),
+      connected: false,
+      running: false,
+      lastStopAt: Date.now(),
+    });
+    log?.info?.(`[${accountId}] openclaw-clawchat disconnected`);
+  });
+}
+
+// Re-export so channel.ts outbound.sendText can use the streaming helper when needed.
+export { sendStreamingText };