@newbase-clawchat/openclaw-clawchat 2026.5.4 → 2026.5.12-13

package/src/runtime.test.ts

@@ -1,15 +1,220 @@
-import { MockTransport, AuthError } from "@newbase-clawchat/sdk";
 import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk/core";
 import { describe, expect, it, vi } from "vitest";
+import { MockTransport } from "./mock-transport.ts";
+import { AuthError } from "./protocol-types.ts";
 import {
   classifyClawlingClientError,
   mapClawlingStateToStatus,
   setOpenclawClawlingRuntime,
   getOpenclawClawlingRuntime,
+  startOpenclawClawlingGateway,
+  getOpenclawClawlingClient,
 } from "./runtime.ts";
+import type { ResolvedOpenclawClawlingAccount } from "./config.ts";
+import { sendOpenclawClawlingText } from "./outbound.ts";
+
+function baseAccount(
+  overrides: Partial<ResolvedOpenclawClawlingAccount> = {},
+): ResolvedOpenclawClawlingAccount {
+  return {
+    accountId: "default",
+    name: "openclaw-clawchat",
+    enabled: true,
+    configured: true,
+    websocketUrl: "ws://t",
+    baseUrl: "https://api.example.com",
+    token: "tk",
+    userId: "u",
+    ownerUserId: "owner-u",
+    replyMode: "static",
+    groupMode: "all",
+    groups: {},
+    forwardThinking: true,
+    forwardToolCalls: false,
+    richInteractions: 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 },
+    ...overrides,
+  };
+}
+
+const EXPECTED_ACTIVATION_BOOTSTRAP_TEXT = [
+  "ClawChat activation bootstrap: You are now connected to this ClawChat direct conversation.",
+  "Please do both:",
+  "1. Send a brief, friendly greeting to the user in this ClawChat direct conversation.",
+  "2. If you have local profile information for yourself, such as display name, bio, or avatar, update the connected ClawChat account profile using the available ClawChat tools. Use `clawchat_update_account_profile` for display name/bio/avatar URL, and use `clawchat_upload_avatar_image` first if the avatar is only available as a local image path. If you do not have local profile information, skip profile updates and only greet the user.",
+  "Do not ask the user for profile information just for this bootstrap.",
+].join("\n");
+
+const EXPECTED_CLAWCHAT_GROUP_SYSTEM_PROMPT = [
+  "When replying in a ClawChat group, treat the conversation as a shared space. Stay concise, respect the group topic, and avoid exposing hidden runtime context.",
+  "",
+  "**给 Agents**",
+  "你是群组里的伙伴。请理解我们在做的事，理解每一位成员。",
+  "也请通过群慢慢和每个人建立关系——你是我们的一员。",
+  "",
+  "**两条底线**",
+  "1. 被 @ 时必须回复",
+  "2. Agent 之间连续对话不超过 10 轮，除非有人类伙伴明确允许",
+].join("\n");
+
+function buildTestInboundContext(params: {
+  channel: string;
+  accountId?: string;
+  provider?: string;
+  surface?: string;
+  messageId?: string;
+  messageIdFull?: string;
+  timestamp?: number;
+  from: string;
+  sender: { id: string; name?: string; displayLabel?: string };
+  conversation: { kind: "direct" | "group" | "channel"; label?: string };
+  route: { accountId?: string; routeSessionKey: string; dispatchSessionKey?: string };
+  reply: { to: string; originatingTo: string };
+  message: { body?: string; rawBody: string; bodyForAgent?: string; commandBody?: string };
+  access?: { mentions?: { wasMentioned?: boolean } };
+  supplemental?: { groupSystemPrompt?: string };
+}) {
+  return {
+    Body: params.message.body ?? params.message.rawBody,
+    BodyForAgent: params.message.bodyForAgent ?? params.message.rawBody,
+    RawBody: params.message.rawBody,
+    CommandBody: params.message.commandBody ?? params.message.rawBody,
+    From: params.from,
+    To: params.reply.to,
+    SessionKey: params.route.dispatchSessionKey ?? params.route.routeSessionKey,
+    AccountId: params.route.accountId ?? params.accountId,
+    MessageSid: params.messageId,
+    MessageSidFull: params.messageIdFull,
+    ChatType: params.conversation.kind,
+    ConversationLabel: params.conversation.label,
+    GroupSubject: params.conversation.kind !== "direct" ? params.conversation.label : undefined,
+    GroupSystemPrompt: params.supplemental?.groupSystemPrompt,
+    SenderName: params.sender.name ?? params.sender.displayLabel,
+    SenderId: params.sender.id,
+    Timestamp: params.timestamp,
+    Provider: params.provider ?? params.channel,
+    Surface: params.surface ?? params.provider ?? params.channel,
+    WasMentioned: params.access?.mentions?.wasMentioned,
+    OriginatingChannel: params.channel,
+    OriginatingTo: params.reply.originatingTo,
+  };
+}
+
+async function completeHandshake(
+  transport: MockTransport,
+  challengeTraceId = "challenge-bootstrap",
+  helloPayload: Record<string, unknown> = {},
+): Promise<Record<string, unknown>> {
+  await Promise.resolve();
+  transport.emitInbound(
+    JSON.stringify({
+      version: "2",
+      event: "connect.challenge",
+      trace_id: challengeTraceId,
+      emitted_at: Date.now(),
+      payload: { nonce: `${challengeTraceId}-nonce` },
+    }),
+  );
+  const connectFrame = transport.sent
+    .map((raw) => JSON.parse(raw) as Record<string, unknown>)
+    .filter((env) => env.event === "connect")
+    .at(-1)!;
+  transport.emitInbound(
+    JSON.stringify({
+      version: "2",
+      event: "hello-ok",
+      trace_id: connectFrame.trace_id,
+      emitted_at: Date.now(),
+      payload: helloPayload,
+    }),
+  );
+  await Promise.resolve();
+  return connectFrame;
+}
+
+function jsonEnvelope(data: unknown, status = 200): Response {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+function conversationDetails(id: string, overrides: Record<string, unknown> = {}) {
+  return {
+    id,
+    type: "group",
+    title: `Room ${id}`,
+    description: `Description ${id}`,
+    creator_id: "user-owner",
+    created_at: "2026-05-21T10:00:00.000Z",
+    updated_at: "2026-05-21T10:01:00.000Z",
+    participants: [
+      {
+        conversation_id: id,
+        user_id: "user-owner",
+        role: "owner",
+        joined_at: "2026-05-21T10:00:30.000Z",
+        nickname: "Owner",
+        avatar_url: "https://cdn.example/owner.png",
+      },
+    ],
+    ...overrides,
+  };
+}
+
+function buildNoDispatchRuntime(dispatchReplyFromConfig = vi.fn().mockResolvedValue(undefined)) {
+  return {
+    channel: {
+      routing: {
+        resolveAgentRoute: vi.fn(() => ({
+          agentId: "default",
+          accountId: "default",
+          sessionKey: "session-from-route",
+        })),
+      },
+      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: vi.fn((ctx: Record<string, unknown>) => ctx),
+        resolveHumanDelayConfig: vi.fn(() => ({ enabled: false })),
+        createReplyDispatcherWithTyping: vi.fn(() => ({
+          dispatcher: {},
+          replyOptions: {},
+          markDispatchIdle: vi.fn(),
+          markRunComplete: vi.fn(),
+        })),
+        withReplyDispatcher: vi.fn(async (opts: { run: () => Promise<unknown> }) => opts.run()),
+        dispatchReplyFromConfig,
+      },
+      turn: {
+        buildContext: vi.fn((params) =>
+          buildTestInboundContext(params as Parameters<typeof buildTestInboundContext>[0]),
+        ),
+      },
+      media: {
+        fetchRemoteMedia: vi.fn(),
+        saveMediaBuffer: vi.fn(),
+        loadWebMedia: vi.fn(),
+      },
+    },
+  } as unknown as PluginRuntime;
+}
 
 describe("openclaw-clawchat runtime helpers", () => {
-  it("maps SDK states to channel status shape", () => {
+  it("maps local client states to channel status shape", () => {
     expect(mapClawlingStateToStatus("connected")).toMatchObject({
       connected: true,
       running: true,
@@ -18,43 +223,1746 @@ describe("openclaw-clawchat runtime helpers", () => {
       connected: false,
       running: true,
     });
-    expect(mapClawlingStateToStatus("disconnected")).toMatchObject({
-      connected: false,
-      running: false,
+    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("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);
+  });
+
+  it("logs auth_failed and does not reconnect after hello-fail", async () => {
+    const logs: string[] = [];
+    const transport = new MockTransport();
+    const account = baseAccount();
+    const abortController = new AbortController();
+
+    setOpenclawClawlingRuntime({ mocked: true } as unknown as PluginRuntime);
+    const run = startOpenclawClawlingGateway({
+      cfg: {},
+      account,
+      abortSignal: abortController.signal,
+      setStatus: () => {},
+      getStatus: () => ({ connected: false, configured: true, running: true }),
+      log: { info: (msg) => logs.push(msg), error: (msg) => logs.push(msg) },
+      transport,
+    });
+
+    await Promise.resolve();
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "connect.challenge",
+        trace_id: "challenge-1",
+        emitted_at: Date.now(),
+        payload: { nonce: "nonce-1" },
+      }),
+    );
+    const connectFrame = transport.sent
+      .map((raw) => JSON.parse(raw))
+      .find((env) => env.event === "connect");
+    expect(logs).toContain(
+      "clawchat.ws event=connect_start account_id=default attempt=1 reconnect_count=0 state=connecting action=connect url=ws://t queue_size=0",
+    );
+    expect(logs).toContain(
+      "clawchat.ws event=challenge_received account_id=default attempt=1 reconnect_count=0 state=handshaking action=send_connect challenge_trace_id=challenge-1 has_nonce=true",
+    );
+    expect(logs).toContain(
+      "clawchat.ws event=connect_sent account_id=default attempt=1 reconnect_count=0 state=handshaking action=await_hello trace_id=" +
+        connectFrame.trace_id +
+        " device_id=u",
+    );
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "hello-fail",
+        trace_id: connectFrame.trace_id,
+        emitted_at: Date.now(),
+        payload: { reason: "authentication failed" },
+      }),
+    );
+
+    await run;
+
+    expect(logs).toContain(
+      "clawchat.ws event=auth_failed account_id=default attempt=1 reconnect_count=0 state=auth_failed action=stop_reconnect trace_id=" +
+        connectFrame.trace_id +
+        " reason=authentication failed",
+    );
+    expect(logs.some((line) => line.includes("event=handshake_ok"))).toBe(false);
+    expect(logs.some((line) => line.includes("event=reconnect_scheduled"))).toBe(false);
+  });
+
+  it("logs canonical websocket lifecycle for the first successful connect", async () => {
+    const logs: string[] = [];
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    setOpenclawClawlingRuntime({ mocked: true } as unknown as PluginRuntime);
+    const run = startOpenclawClawlingGateway({
+      cfg: {},
+      account: baseAccount(),
+      abortSignal: abortController.signal,
+      setStatus: () => {},
+      getStatus: () => ({ connected: false, configured: true, running: true }),
+      log: { info: (msg) => logs.push(msg), error: (msg) => logs.push(msg) },
+      transport,
+    });
+
+    await Promise.resolve();
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "connect.challenge",
+        trace_id: "challenge-1",
+        emitted_at: Date.now(),
+        payload: { nonce: "nonce-1" },
+      }),
+    );
+    const connectFrame = transport.sent
+      .map((raw) => JSON.parse(raw))
+      .find((env) => env.event === "connect");
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "hello-ok",
+        trace_id: connectFrame.trace_id,
+        emitted_at: Date.now(),
+        payload: {},
+      }),
+    );
+    await Promise.resolve();
+
+    expect(logs).toContain(
+      "clawchat.ws event=connect_start account_id=default attempt=1 reconnect_count=0 state=connecting action=connect url=ws://t queue_size=0",
+    );
+    expect(logs).toContain(
+      "clawchat.ws event=challenge_received account_id=default attempt=1 reconnect_count=0 state=handshaking action=send_connect challenge_trace_id=challenge-1 has_nonce=true",
+    );
+    expect(logs).toContain(
+      "clawchat.ws event=connect_sent account_id=default attempt=1 reconnect_count=0 state=handshaking action=await_hello trace_id=" +
+        connectFrame.trace_id +
+        " device_id=u",
+    );
+    expect(logs).toContainEqual(
+      expect.stringMatching(
+        new RegExp(
+          "^clawchat\\.ws event=handshake_ok account_id=default attempt=1 reconnect_count=0 state=ready action=flush_queue trace_id=" +
+            connectFrame.trace_id +
+            " elapsed_ms=\\d+ queue_size=0$",
+        ),
+      ),
+    );
+
+    abortController.abort();
+    await run;
+  });
+
+  it("records websocket lifecycle calls in connection order", async () => {
+    const calls: string[] = [];
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+    const store = {
+      startConnection: vi.fn(() => {
+        calls.push("startConnection");
+        return 101;
+      }),
+      markConnectSent: vi.fn(() => calls.push("markConnectSent")),
+      markConnectionReady: vi.fn(() => calls.push("markConnectionReady")),
+      finishConnection: vi.fn((_id, input) => calls.push(`finishConnection:${input.state}`)),
+    };
+
+    setOpenclawClawlingRuntime({ mocked: true } as unknown as PluginRuntime);
+    const run = startOpenclawClawlingGateway({
+      cfg: {},
+      account: baseAccount(),
+      abortSignal: abortController.signal,
+      setStatus: () => {},
+      getStatus: () => ({ connected: false, configured: true, running: true }),
+      log: { info: vi.fn(), error: vi.fn() },
+      transport,
+      store,
+    });
+
+    await Promise.resolve();
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "connect.challenge",
+        trace_id: "challenge-1",
+        emitted_at: Date.now(),
+        payload: { nonce: "nonce-1" },
+      }),
+    );
+    const connectFrame = transport.sent
+      .map((raw) => JSON.parse(raw))
+      .find((env) => env.event === "connect");
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "hello-ok",
+        trace_id: connectFrame.trace_id,
+        emitted_at: Date.now(),
+        payload: {},
+      }),
+    );
+    await Promise.resolve();
+
+    abortController.abort();
+    await run;
+
+    expect(calls).toEqual([
+      "startConnection",
+      "markConnectSent",
+      "markConnectionReady",
+      "finishConnection:disconnected",
+    ]);
+    expect(store.startConnection).toHaveBeenCalledWith(
+      expect.objectContaining({
+        platform: "openclaw",
+        accountId: "default",
+        attempt: 1,
+        reconnectCount: 0,
+      }),
+    );
+    expect(store.markConnectSent).toHaveBeenCalledWith(101);
+    expect(store.markConnectionReady).toHaveBeenCalledWith(101);
+    expect(store.finishConnection).toHaveBeenCalledWith(
+      101,
+      expect.objectContaining({ state: "disconnected", closeCode: 1000 }),
+    );
+  });
+
+  it("records hello-ok device metadata when marking a connection ready", async () => {
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+    const store = {
+      startConnection: vi.fn(() => 111),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+    };
+
+    setOpenclawClawlingRuntime({ mocked: true } as unknown as PluginRuntime);
+    const run = startOpenclawClawlingGateway({
+      cfg: {},
+      account: baseAccount(),
+      abortSignal: abortController.signal,
+      setStatus: () => {},
+      getStatus: () => ({ connected: false, configured: true, running: true }),
+      log: { info: vi.fn(), error: vi.fn() },
+      transport,
+      store,
+    });
+
+    await Promise.resolve();
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "connect.challenge",
+        trace_id: "challenge-1",
+        emitted_at: Date.now(),
+        payload: { nonce: "nonce-1" },
+      }),
+    );
+    const connectFrame = transport.sent
+      .map((raw) => JSON.parse(raw))
+      .find((env) => env.event === "connect");
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "hello-ok",
+        trace_id: connectFrame.trace_id,
+        emitted_at: Date.now(),
+        payload: { device_id: "device-resolved", delivery_mode: "device_replay" },
+      }),
+    );
+    await Promise.resolve();
+
+    abortController.abort();
+    await run;
+
+    expect(store.markConnectionReady).toHaveBeenCalledWith(
+      111,
+      expect.objectContaining({
+        resolvedDeviceId: "device-resolved",
+        deliveryMode: "device_replay",
+      }),
+    );
+  });
+
+  it("refreshes metadata invalidations without dispatching an agent turn", async () => {
+    const dispatchReplyFromConfig = vi.fn().mockResolvedValue(undefined);
+    const runtime = buildNoDispatchRuntime(dispatchReplyFromConfig);
+    const fetchMock = vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      jsonEnvelope({ code: 0, msg: "ok", data: { conversation: conversationDetails("group-1") } }),
+    );
+    const store = {
+      startConnection: vi.fn(() => 121),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+      getCachedConversation: vi.fn(() => ({
+        conversationId: "group-1",
+        conversationType: "group",
+        metadataVersion: 4,
+        lastSeenAt: 1,
+        lastRefreshedAt: 1,
+      })),
+      upsertConversationDetails: vi.fn(),
+      deleteConversationCache: vi.fn(),
+    };
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    try {
+      setOpenclawClawlingRuntime(runtime);
+      const run = startOpenclawClawlingGateway({
+        cfg: {},
+        account: baseAccount(),
+        abortSignal: abortController.signal,
+        setStatus: vi.fn(),
+        getStatus: vi.fn(() => ({ connected: false, configured: true, running: true })),
+        log: { info: vi.fn(), error: vi.fn() },
+        transport,
+        store: store as NonNullable<Parameters<typeof startOpenclawClawlingGateway>[0]["store"]>,
+      });
+
+      await completeHandshake(transport, "challenge-meta-refresh");
+      transport.emitInbound(JSON.stringify({
+        version: "2",
+        event: "chat.metadata.invalidated",
+        trace_id: "meta-refresh",
+        emitted_at: Date.now(),
+        chat_id: "group-1",
+        chat_type: "group",
+        payload: { scope: ["unknown"], version: 7 },
+      }));
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      expect(fetchMock).toHaveBeenCalledWith(
+        "https://api.example.com/v1/conversations/group-1",
+        expect.objectContaining({ method: "GET" }),
+      );
+      expect(store.upsertConversationDetails).toHaveBeenCalledWith(expect.objectContaining({
+        platform: "openclaw",
+        accountId: "default",
+        conversationId: "group-1",
+        conversationType: "group",
+        metadataVersion: 7,
+        groupProfile: expect.objectContaining({ title: "Room group-1", metadataVersion: 7 }),
+        userProfiles: [expect.objectContaining({ userId: "user-owner", nickname: "Owner" })],
+        members: [expect.objectContaining({ userId: "user-owner", role: "owner" })],
+        membersComplete: true,
+      }));
+      expect(dispatchReplyFromConfig).not.toHaveBeenCalled();
+
+      abortController.abort();
+      await run;
+    } finally {
+      fetchMock.mockRestore();
+    }
+  });
+
+  it("logs metadata invalidations without chat_id and skips stale versions", async () => {
+    const logs: string[] = [];
+    const runtime = buildNoDispatchRuntime();
+    const fetchMock = vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      jsonEnvelope({ code: 0, msg: "ok", data: { conversation: conversationDetails("group-stale") } }),
+    );
+    const store = {
+      startConnection: vi.fn(() => 122),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+      getCachedConversation: vi.fn(() => ({
+        conversationId: "group-stale",
+        conversationType: "group",
+        metadataVersion: 9,
+        lastSeenAt: 1,
+        lastRefreshedAt: 1,
+      })),
+      upsertConversationDetails: vi.fn(),
+    };
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    try {
+      setOpenclawClawlingRuntime(runtime);
+      const run = startOpenclawClawlingGateway({
+        cfg: {},
+        account: baseAccount(),
+        abortSignal: abortController.signal,
+        setStatus: vi.fn(),
+        getStatus: vi.fn(() => ({ connected: false, configured: true, running: true })),
+        log: { info: (msg) => logs.push(msg), error: (msg) => logs.push(msg) },
+        transport,
+        store: store as NonNullable<Parameters<typeof startOpenclawClawlingGateway>[0]["store"]>,
+      });
+
+      await completeHandshake(transport, "challenge-meta-stale");
+      transport.emitInbound(JSON.stringify({
+        version: "2",
+        event: "chat.metadata.invalidated",
+        trace_id: "meta-missing-chat",
+        emitted_at: Date.now(),
+        payload: { version: 10 },
+      }));
+      transport.emitInbound(JSON.stringify({
+        version: "2",
+        event: "chat.metadata.invalidated",
+        trace_id: "meta-stale",
+        emitted_at: Date.now(),
+        chat_id: "group-stale",
+        payload: { version: 9 },
+      }));
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      expect(fetchMock).not.toHaveBeenCalled();
+      expect(store.upsertConversationDetails).not.toHaveBeenCalled();
+      expect(logs.some((line) => line.includes("metadata invalidation missing chat_id"))).toBe(true);
+
+      abortController.abort();
+      await run;
+    } finally {
+      fetchMock.mockRestore();
+    }
+  });
+
+  it("refreshes metadata invalidations without a version and deletes scoped cache on not found", async () => {
+    const runtime = buildNoDispatchRuntime();
+    const fetchMock = vi.spyOn(globalThis, "fetch")
+      .mockResolvedValueOnce(jsonEnvelope({ code: 0, msg: "ok", data: { conversation: conversationDetails("group-no-version") } }))
+      .mockResolvedValueOnce(jsonEnvelope({ code: 404, msg: "conversation not found", data: {} }));
+    const store = {
+      startConnection: vi.fn(() => 123),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+      getCachedConversation: vi.fn(() => ({
+        conversationId: "group-no-version",
+        conversationType: "group",
+        metadataVersion: 99,
+        lastSeenAt: 1,
+        lastRefreshedAt: 1,
+      })),
+      upsertConversationDetails: vi.fn(),
+      deleteConversationCache: vi.fn(),
+    };
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    try {
+      setOpenclawClawlingRuntime(runtime);
+      const run = startOpenclawClawlingGateway({
+        cfg: {},
+        account: baseAccount(),
+        abortSignal: abortController.signal,
+        setStatus: vi.fn(),
+        getStatus: vi.fn(() => ({ connected: false, configured: true, running: true })),
+        log: { info: vi.fn(), error: vi.fn() },
+        transport,
+        store: store as NonNullable<Parameters<typeof startOpenclawClawlingGateway>[0]["store"]>,
+      });
+
+      await completeHandshake(transport, "challenge-meta-noversion");
+      transport.emitInbound(JSON.stringify({
+        version: "2",
+        event: "chat.metadata.invalidated",
+        trace_id: "meta-no-version",
+        emitted_at: Date.now(),
+        chat_id: "group-no-version",
+        payload: {},
+      }));
+      transport.emitInbound(JSON.stringify({
+        version: "2",
+        event: "chat.metadata.invalidated",
+        trace_id: "meta-not-found",
+        emitted_at: Date.now(),
+        chat_id: "group-missing",
+        payload: { version: 100 },
+      }));
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      expect(store.upsertConversationDetails).toHaveBeenCalledWith(expect.objectContaining({
+        conversationId: "group-no-version",
+      }));
+      expect(store.deleteConversationCache).toHaveBeenCalledWith({
+        platform: "openclaw",
+        accountId: "default",
+        conversationId: "group-missing",
+      });
+
+      abortController.abort();
+      await run;
+    } finally {
+      fetchMock.mockRestore();
+    }
+  });
+
+  it("logs metadata refresh errors without advancing the cached version", async () => {
+    const logs: string[] = [];
+    const runtime = buildNoDispatchRuntime();
+    const fetchMock = vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response("gateway unavailable", { status: 500 }),
+    );
+    const store = {
+      startConnection: vi.fn(() => 124),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+      getCachedConversation: vi.fn(() => ({
+        conversationId: "group-error",
+        conversationType: "group",
+        metadataVersion: 1,
+        lastSeenAt: 1,
+        lastRefreshedAt: 1,
+      })),
+      upsertConversationDetails: vi.fn(),
+      deleteConversationCache: vi.fn(),
+    };
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    try {
+      setOpenclawClawlingRuntime(runtime);
+      const run = startOpenclawClawlingGateway({
+        cfg: {},
+        account: baseAccount(),
+        abortSignal: abortController.signal,
+        setStatus: vi.fn(),
+        getStatus: vi.fn(() => ({ connected: false, configured: true, running: true })),
+        log: { info: (msg) => logs.push(msg), error: (msg) => logs.push(msg) },
+        transport,
+        store: store as NonNullable<Parameters<typeof startOpenclawClawlingGateway>[0]["store"]>,
+      });
+
+      await completeHandshake(transport, "challenge-meta-error");
+      transport.emitInbound(JSON.stringify({
+        version: "2",
+        event: "chat.metadata.invalidated",
+        trace_id: "meta-error",
+        emitted_at: Date.now(),
+        chat_id: "group-error",
+        payload: { version: 2 },
+      }));
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      expect(store.upsertConversationDetails).not.toHaveBeenCalled();
+      expect(store.deleteConversationCache).not.toHaveBeenCalled();
+      expect(logs.some((line) => line.includes("metadata refresh failed"))).toBe(true);
+
+      abortController.abort();
+      await run;
+    } finally {
+      fetchMock.mockRestore();
+    }
+  });
+
+  it("refreshes activation and cached conversations after hello-ok without writing tool calls", async () => {
+    const runtime = buildNoDispatchRuntime();
+    const requestedIds: string[] = [];
+    const fetchMock = vi.spyOn(globalThis, "fetch").mockImplementation(async (input) => {
+      const id = String(input).split("/").at(-1)!;
+      requestedIds.push(id);
+      if (id === "cached-fail") {
+        return new Response("oops", { status: 500 });
+      }
+      return jsonEnvelope({ code: 0, msg: "ok", data: { conversation: conversationDetails(id) } });
+    });
+    const cachedIds = ["cached-1", "activation-1", "cached-fail", ...Array.from({ length: 25 }, (_, i) => `cached-${i + 2}`)];
+    const store = {
+      startConnection: vi.fn(() => 125),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+      getActivationConversation: vi.fn(() => ({
+        conversationId: "activation-1",
+        conversationType: "direct",
+        metadataVersion: null,
+        lastSeenAt: null,
+        lastRefreshedAt: null,
+      })),
+      listCachedConversationIds: vi.fn(() => cachedIds),
+      upsertConversationDetails: vi.fn(),
+      deleteConversationCache: vi.fn(),
+      recordToolCall: vi.fn(),
+    };
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    try {
+      setOpenclawClawlingRuntime(runtime);
+      const run = startOpenclawClawlingGateway({
+        cfg: {},
+        account: baseAccount(),
+        abortSignal: abortController.signal,
+        setStatus: vi.fn(),
+        getStatus: vi.fn(() => ({ connected: false, configured: true, running: true })),
+        log: { info: vi.fn(), error: vi.fn() },
+        transport,
+        store: store as NonNullable<Parameters<typeof startOpenclawClawlingGateway>[0]["store"]>,
+      });
+
+      await completeHandshake(transport, "challenge-fresh-fetch");
+      await new Promise((resolve) => setTimeout(resolve, 30));
+
+      expect(store.listCachedConversationIds).toHaveBeenCalledWith({
+        platform: "openclaw",
+        accountId: "default",
+        limit: 20,
+      });
+      expect(requestedIds[0]).toBe("activation-1");
+      expect(requestedIds.filter((id) => id === "activation-1")).toHaveLength(1);
+      expect(requestedIds).toContain("cached-1");
+      expect(requestedIds).toContain("cached-fail");
+      expect(store.upsertConversationDetails).toHaveBeenCalledWith(expect.objectContaining({
+        conversationId: "cached-1",
+      }));
+      expect(store.upsertConversationDetails).toHaveBeenCalledWith(expect.objectContaining({
+        conversationId: "cached-2",
+      }));
+      expect(store.recordToolCall).not.toHaveBeenCalled();
+
+      abortController.abort();
+      await run;
+    } finally {
+      fetchMock.mockRestore();
+    }
+  });
+
+  it("records auth failure and transport error as terminal connection states", async () => {
+    const authTransport = new MockTransport();
+    const authStore = {
+      startConnection: vi.fn(() => 201),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+    };
+
+    setOpenclawClawlingRuntime({ mocked: true } as unknown as PluginRuntime);
+    const authRun = startOpenclawClawlingGateway({
+      cfg: {},
+      account: baseAccount(),
+      abortSignal: new AbortController().signal,
+      setStatus: () => {},
+      getStatus: () => ({ connected: false, configured: true, running: true }),
+      log: { info: vi.fn(), error: vi.fn() },
+      transport: authTransport,
+      store: authStore,
+    });
+
+    await Promise.resolve();
+    authTransport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "connect.challenge",
+        trace_id: "challenge-auth",
+        emitted_at: Date.now(),
+        payload: { nonce: "nonce-1" },
+      }),
+    );
+    const authConnectFrame = authTransport.sent
+      .map((raw) => JSON.parse(raw))
+      .find((env) => env.event === "connect");
+    authTransport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "hello-fail",
+        trace_id: authConnectFrame.trace_id,
+        emitted_at: Date.now(),
+        payload: { reason: "authentication failed" },
+      }),
+    );
+
+    await authRun;
+
+    expect(authStore.finishConnection).toHaveBeenCalledWith(
+      201,
+      expect.objectContaining({ state: "auth_failed", error: "authentication failed" }),
+    );
+
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+    const transportStore = {
+      startConnection: vi.fn(() => 301),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+    };
+    const transportRun = startOpenclawClawlingGateway({
+      cfg: {},
+      account: baseAccount(),
+      abortSignal: abortController.signal,
+      setStatus: () => {},
+      getStatus: () => ({ connected: false, configured: true, running: true }),
+      log: { info: vi.fn(), error: vi.fn() },
+      transport,
+      store: transportStore,
+    });
+
+    await Promise.resolve();
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "connect.challenge",
+        trace_id: "challenge-transport",
+        emitted_at: Date.now(),
+        payload: { nonce: "nonce-1" },
+      }),
+    );
+    const transportConnectFrame = transport.sent
+      .map((raw) => JSON.parse(raw))
+      .find((env) => env.event === "connect");
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "hello-ok",
+        trace_id: transportConnectFrame.trace_id,
+        emitted_at: Date.now(),
+        payload: {},
+      }),
+    );
+    await Promise.resolve();
+    transport.emitError(new Error("socket down"));
+    await Promise.resolve();
+    abortController.abort();
+    await transportRun;
+
+    expect(transportStore.finishConnection).toHaveBeenCalledWith(
+      301,
+      expect.objectContaining({ state: "transport_error", error: "socket down" }),
+    );
+  });
+
+  it("logs handshake_ok with the connect trace", async () => {
+    const logs: string[] = [];
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    setOpenclawClawlingRuntime({ mocked: true } as unknown as PluginRuntime);
+    const run = startOpenclawClawlingGateway({
+      cfg: {},
+      account: baseAccount(),
+      abortSignal: abortController.signal,
+      setStatus: () => {},
+      getStatus: () => ({ connected: false, configured: true, running: true }),
+      log: { info: (msg) => logs.push(msg), error: (msg) => logs.push(msg) },
+      transport,
+    });
+
+    await Promise.resolve();
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "connect.challenge",
+        trace_id: "challenge-1",
+        emitted_at: Date.now(),
+        payload: { nonce: "nonce-1" },
+      }),
+    );
+    const connectFrame = transport.sent
+      .map((raw) => JSON.parse(raw))
+      .find((env) => env.event === "connect");
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "hello-ok",
+        trace_id: connectFrame.trace_id,
+        emitted_at: Date.now(),
+        payload: {},
+      }),
+    );
+    await Promise.resolve();
+
+    expect(logs).toContainEqual(
+      expect.stringMatching(
+        new RegExp(
+          "^clawchat\\.ws event=handshake_ok account_id=default attempt=1 reconnect_count=0 state=ready action=flush_queue trace_id=" +
+            connectFrame.trace_id +
+            " elapsed_ms=\\d+ queue_size=0$",
+        ),
+      ),
+    );
+
+    abortController.abort();
+    await run;
+  });
+
+  it("logs JSON ping and pong as protocol control", async () => {
+    const logs: string[] = [];
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    setOpenclawClawlingRuntime({ mocked: true } as unknown as PluginRuntime);
+    const run = startOpenclawClawlingGateway({
+      cfg: {},
+      account: baseAccount(),
+      abortSignal: abortController.signal,
+      setStatus: () => {},
+      getStatus: () => ({ connected: false, configured: true, running: true }),
+      log: { info: (msg) => logs.push(msg), error: (msg) => logs.push(msg) },
+      transport,
+    });
+
+    await Promise.resolve();
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "connect.challenge",
+        trace_id: "challenge-1",
+        emitted_at: Date.now(),
+        payload: { nonce: "nonce-1" },
+      }),
+    );
+    const connectFrame = transport.sent
+      .map((raw) => JSON.parse(raw))
+      .find((env) => env.event === "connect");
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "hello-ok",
+        trace_id: connectFrame.trace_id,
+        emitted_at: Date.now(),
+        payload: {},
+      }),
+    );
+    await Promise.resolve();
+    transport.sent.length = 0;
+
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "ping",
+        trace_id: "trace-ping",
+        emitted_at: Date.now(),
+        payload: {},
+      }),
+    );
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "pong",
+        trace_id: "trace-pong",
+        emitted_at: Date.now(),
+        payload: {},
+      }),
+    );
+
+    expect(transport.sent.map((raw) => JSON.parse(raw))).toContainEqual(
+      expect.objectContaining({ event: "pong", trace_id: "trace-ping" }),
+    );
+    expect(logs).toContain(
+      "clawchat.ws event=protocol_ping_received account_id=default attempt=1 reconnect_count=0 state=ready action=send_pong trace_id=trace-ping",
+    );
+    expect(logs).toContain(
+      "clawchat.ws event=protocol_pong_received account_id=default attempt=1 reconnect_count=0 state=ready action=ignore trace_id=trace-pong",
+    );
+
+    abortController.abort();
+    await run;
+  });
+
+  it("logs unknown ready-state events as inbound_ignored", async () => {
+    const logs: string[] = [];
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    setOpenclawClawlingRuntime({ mocked: true } as unknown as PluginRuntime);
+    const run = startOpenclawClawlingGateway({
+      cfg: {},
+      account: baseAccount(),
+      abortSignal: abortController.signal,
+      setStatus: () => {},
+      getStatus: () => ({ connected: false, configured: true, running: true }),
+      log: { info: (msg) => logs.push(msg), error: (msg) => logs.push(msg) },
+      transport,
+    });
+
+    await Promise.resolve();
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "connect.challenge",
+        trace_id: "challenge-1",
+        emitted_at: Date.now(),
+        payload: { nonce: "nonce-1" },
+      }),
+    );
+    const connectFrame = transport.sent
+      .map((raw) => JSON.parse(raw))
+      .find((env) => env.event === "connect");
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "hello-ok",
+        trace_id: connectFrame.trace_id,
+        emitted_at: Date.now(),
+        payload: {},
+      }),
+    );
+    await Promise.resolve();
+
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "custom.event",
+        trace_id: "trace-custom",
+        emitted_at: Date.now(),
+        payload: {},
+      }),
+    );
+
+    expect(logs).toContain(
+      "clawchat.ws event=inbound_ignored account_id=default attempt=1 reconnect_count=0 state=ready action=ignore event_name=custom.event trace_id=trace-custom",
+    );
+
+    abortController.abort();
+    await run;
+  });
+
+  it("auto flushes queued outbound when runtime observes connected", async () => {
+    const logs: string[] = [];
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+    const account = baseAccount({
+      ack: { timeout: 15000, autoResendOnTimeout: false },
+      reconnect: {
+        initialDelay: 1,
+        maxDelay: 1,
+        jitterRatio: 0,
+        maxRetries: Number.POSITIVE_INFINITY,
+      },
+    });
+
+    setOpenclawClawlingRuntime({ mocked: true } as unknown as PluginRuntime);
+    const run = startOpenclawClawlingGateway({
+      cfg: {},
+      account,
+      abortSignal: abortController.signal,
+      setStatus: () => {},
+      getStatus: () => ({ connected: false, configured: true, running: true }),
+      log: { info: (msg) => logs.push(msg), error: (msg) => logs.push(msg) },
+      transport,
+    });
+
+    await Promise.resolve();
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "connect.challenge",
+        trace_id: "challenge-1",
+        emitted_at: Date.now(),
+        payload: { nonce: "nonce-1" },
+      }),
+    );
+    const connectFrame = transport.sent
+      .map((raw) => JSON.parse(raw))
+      .find((env) => env.event === "connect");
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "hello-ok",
+        trace_id: connectFrame.trace_id,
+        emitted_at: Date.now(),
+        payload: {},
+      }),
+    );
+    await new Promise((resolve) => setTimeout(resolve, 5));
+
+    const client = getOpenclawClawlingClient("default")!;
+    transport.close(1006, "network lost");
+    await Promise.resolve();
+
+    let sendResult: unknown;
+    const sendPromise = sendOpenclawClawlingText({
+      client,
+      account,
+      to: { chatId: "chat-1", chatType: "direct" },
+      text: "queued while reconnecting",
+      log: { info: (msg) => logs.push(msg), error: (msg) => logs.push(msg) },
+    }).then((result) => {
+      sendResult = result;
+      return result;
+    });
+    await Promise.resolve();
+
+    const sentBeforeReady = transport.sent.length;
+    expect(logs.some((line) => line.includes("event=send_queued"))).toBe(true);
+
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "connect.challenge",
+        trace_id: "challenge-2",
+        emitted_at: Date.now(),
+        payload: { nonce: "nonce-2" },
+      }),
+    );
+    const secondConnectFrame = transport.sent
+      .map((raw) => JSON.parse(raw))
+      .filter((env) => env.event === "connect")
+      .at(-1);
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "hello-ok",
+        trace_id: secondConnectFrame.trace_id,
+        emitted_at: Date.now(),
+        payload: {},
+      }),
+    );
+    await Promise.resolve();
+
+    expect(logs).toContainEqual(
+      expect.stringMatching(
+        /^clawchat\.ws event=handshake_ok account_id=default attempt=2 reconnect_count=1 state=ready action=flush_queue trace_id=[^ ]+ elapsed_ms=\d+ queue_size=1$/,
+      ),
+    );
+    expect(transport.sent.length).toBe(sentBeforeReady + 2);
+    const queuedFrame = JSON.parse(transport.sent.at(-1)!);
+    expect(queuedFrame.event).toBe("message.send");
+    expect(logs.some((line) => line.includes("event=send_flush"))).toBe(true);
+
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "message.ack",
+        trace_id: queuedFrame.trace_id,
+        emitted_at: Date.now(),
+        chat_id: "chat-1",
+        payload: { message_id: "server-1", accepted_at: 1234 },
+      }),
+    );
+    await sendPromise;
+    expect(sendResult).toEqual({ messageId: "server-1", acceptedAt: 1234 });
+
+    abortController.abort();
+    await run;
+  });
+
+  it("uses real attempt and reconnect_count in websocket logs across reconnect", async () => {
+    vi.useFakeTimers();
+    const logs: string[] = [];
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    setOpenclawClawlingRuntime({ mocked: true } as unknown as PluginRuntime);
+    const run = startOpenclawClawlingGateway({
+      cfg: {},
+      account: baseAccount({
+        reconnect: {
+          initialDelay: 1000,
+          maxDelay: 30000,
+          jitterRatio: 0,
+          maxRetries: Number.POSITIVE_INFINITY,
+        },
+      }),
+      abortSignal: abortController.signal,
+      setStatus: () => {},
+      getStatus: () => ({ connected: false, configured: true, running: true }),
+      log: { info: (msg) => logs.push(msg), error: (msg) => logs.push(msg) },
+      transport,
+    });
+
+    await Promise.resolve();
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "connect.challenge",
+        trace_id: "challenge-1",
+        emitted_at: Date.now(),
+        payload: { nonce: "nonce-1" },
+      }),
+    );
+    const firstConnectFrame = transport.sent
+      .map((raw) => JSON.parse(raw))
+      .find((env) => env.event === "connect");
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "hello-ok",
+        trace_id: firstConnectFrame.trace_id,
+        emitted_at: Date.now(),
+        payload: {},
+      }),
+    );
+    await Promise.resolve();
+
+    transport.close(1006, "network lost");
+    await Promise.resolve();
+    expect(logs).toContain(
+      "clawchat.ws event=connection_lost account_id=default attempt=1 reconnect_count=0 state=ready action=reconnect code=1006 reason=network lost",
+    );
+    expect(logs).toContain(
+      "clawchat.ws event=reconnect_scheduled account_id=default attempt=1 reconnect_count=1 state=reconnecting action=wait delay_ms=1000 max_delay_ms=30000 reason=connection_lost",
+    );
+
+    await vi.advanceTimersByTimeAsync(1000);
+    await Promise.resolve();
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "connect.challenge",
+        trace_id: "challenge-2",
+        emitted_at: Date.now(),
+        payload: { nonce: "nonce-2" },
+      }),
+    );
+    const secondConnectFrame = transport.sent
+      .map((raw) => JSON.parse(raw))
+      .filter((env) => env.event === "connect")
+      .at(-1);
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "hello-ok",
+        trace_id: secondConnectFrame.trace_id,
+        emitted_at: Date.now(),
+        payload: {},
+      }),
+    );
+    await Promise.resolve();
+
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "custom.event",
+        trace_id: "trace-after-reconnect",
+        emitted_at: Date.now(),
+        payload: {},
+      }),
+    );
+    expect(logs).toContain(
+      "clawchat.ws event=inbound_ignored account_id=default attempt=2 reconnect_count=1 state=ready action=ignore event_name=custom.event trace_id=trace-after-reconnect",
+    );
+
+    await vi.advanceTimersByTimeAsync(5000);
+    expect(logs).toContain(
+      "clawchat.ws event=reconnect_backoff_reset account_id=default attempt=2 reconnect_count=0 state=ready action=reset stable_ms=5000",
+    );
+
+    abortController.abort();
+    await run;
+    vi.useRealTimers();
+  });
+});
+
+describe("openclaw-clawchat runtime media ingest", () => {
+  it("claims complete inbound messages but not streaming created/add fragments", async () => {
+    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: vi.fn((ctx: Record<string, unknown>) => ctx),
+          resolveHumanDelayConfig: vi.fn(() => ({ enabled: false })),
+          createReplyDispatcherWithTyping: vi.fn(() => ({
+            dispatcher: {},
+            replyOptions: {},
+            markDispatchIdle: vi.fn(),
+          })),
+          withReplyDispatcher: vi.fn(async (opts: { run: () => Promise<unknown> }) => {
+            await opts.run();
+          }),
+          dispatchReplyFromConfig: vi.fn().mockResolvedValue(undefined),
+        },
+        turn: {
+          buildContext: vi.fn((params) =>
+            buildTestInboundContext(params as Parameters<typeof buildTestInboundContext>[0]),
+          ),
+        },
+        media: {
+          fetchRemoteMedia: vi.fn(),
+          saveMediaBuffer: vi.fn(),
+          loadWebMedia: vi.fn(),
+        },
+      },
+    } as unknown as PluginRuntime;
+    const store = {
+      startConnection: vi.fn(() => 401),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+      claimMessageOnce: vi.fn(() => true),
+      insertMessage: vi.fn(),
+      upsertConversationSummary: vi.fn(),
+      upsertConversationDetails: vi.fn(),
+    };
+    setOpenclawClawlingRuntime(runtime);
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+    const run = startOpenclawClawlingGateway({
+      cfg: {},
+      account: baseAccount(),
+      abortSignal: abortController.signal,
+      setStatus: vi.fn(),
+      getStatus: vi.fn(() => ({ connected: false, configured: true, running: true })),
+      log: { info: vi.fn(), error: vi.fn() },
+      transport,
+      store,
+    });
+
+    await Promise.resolve();
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "connect.challenge",
+        trace_id: "challenge-inbound-persist",
+        emitted_at: Date.now(),
+        payload: { nonce: "nonce" },
+      }),
+    );
+    const connectFrame = transport.sent
+      .map((raw) => JSON.parse(raw))
+      .find((env) => env.event === "connect");
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "hello-ok",
+        trace_id: connectFrame.trace_id,
+        emitted_at: Date.now(),
+        payload: {},
+      }),
+    );
+    await Promise.resolve();
+
+    for (const event of ["message.created", "message.add"]) {
+      transport.emitInbound(
+        JSON.stringify({
+          version: "2",
+          event,
+          trace_id: `trace-${event}`,
+          emitted_at: Date.now(),
+          chat_id: "chat-1",
+          chat_type: "direct",
+          sender: { id: "user-1", type: "direct", nick_name: "User" },
+          payload: { message_id: "stream-fragment", fragments: [{ kind: "text", text: "part" }] },
+        }),
+      );
+    }
+
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "message.send",
+        trace_id: "trace-inbound-complete",
+        emitted_at: 12345,
+        chat_id: "chat-1",
+        chat_type: "direct",
+        to: { id: "u", type: "direct" },
+        sender: { id: "user-1", type: "direct", nick_name: "User" },
+        payload: {
+          message_id: "m-persist-inbound",
+          message_mode: "normal",
+          message: {
+            body: { fragments: [{ kind: "text", text: "hello persisted" }] },
+            context: { mentions: [], reply: null },
+            streaming: {
+              status: "static",
+              sequence: 0,
+              mutation_policy: "sealed",
+              started_at: null,
+              completed_at: null,
+            },
+          },
+        },
+      }),
+    );
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    abortController.abort();
+    await run;
+
+    expect(store.claimMessageOnce).toHaveBeenCalledTimes(1);
+    expect(store.upsertConversationSummary).toHaveBeenCalledTimes(1);
+    expect(store.upsertConversationSummary).toHaveBeenCalledWith(expect.objectContaining({
+      platform: "openclaw",
+      accountId: "default",
+      conversationId: "chat-1",
+      conversationType: "direct",
+      lastSeenAt: 12345,
+    }));
+    expect(store.upsertConversationDetails).not.toHaveBeenCalled();
+    expect(store.claimMessageOnce).toHaveBeenCalledWith({
+      platform: "openclaw",
+      accountId: "default",
+      kind: "message",
+      direction: "inbound",
+      eventType: "message.send",
+      traceId: "trace-inbound-complete",
+      chatId: "chat-1",
+      messageId: "m-persist-inbound",
+      text: "hello persisted",
+      raw: expect.objectContaining({ event: "message.send" }),
+    });
+    expect(store.insertMessage).not.toHaveBeenCalled();
+  });
+
+  it("does not dispatch duplicate inbound messages already claimed in storage", async () => {
+    const dispatchReplyFromConfig = vi.fn().mockResolvedValue({
+      counts: { final: 1, block: 0, tool: 0 },
+      queuedFinal: true,
+    });
+    const claimMessageOnce = vi.fn().mockReturnValueOnce(true).mockReturnValueOnce(false);
+    const runtime = {
+      channel: {
+        routing: {
+          resolveAgentRoute: vi.fn(() => ({
+            agentId: "default",
+            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: vi.fn((ctx: Record<string, unknown>) => ctx),
+          resolveHumanDelayConfig: vi.fn(() => ({ enabled: false })),
+          createReplyDispatcherWithTyping: vi.fn(() => ({
+            dispatcher: {},
+            replyOptions: {},
+            markDispatchIdle: vi.fn(),
+            markRunComplete: vi.fn(),
+          })),
+          withReplyDispatcher: vi.fn(async (opts: { run: () => Promise<unknown> }) => opts.run()),
+          dispatchReplyFromConfig,
+        },
+        turn: {
+          buildContext: vi.fn((params) =>
+            buildTestInboundContext(params as Parameters<typeof buildTestInboundContext>[0]),
+          ),
+        },
+        media: {
+          fetchRemoteMedia: vi.fn(),
+          saveMediaBuffer: vi.fn(),
+          loadWebMedia: vi.fn(),
+        },
+      },
+    } as unknown as PluginRuntime;
+    setOpenclawClawlingRuntime(runtime);
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    const run = startOpenclawClawlingGateway({
+      cfg: {},
+      account: baseAccount(),
+      abortSignal: abortController.signal,
+      setStatus: vi.fn(),
+      getStatus: vi.fn(() => ({ connected: false, configured: true, running: true })),
+      log: { info: vi.fn(), error: vi.fn() },
+      transport,
+      store: {
+        startConnection: vi.fn(() => 1),
+        markConnectSent: vi.fn(),
+        markConnectionReady: vi.fn(),
+        finishConnection: vi.fn(),
+        claimMessageOnce,
+      },
+    });
+
+    await Promise.resolve();
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "connect.challenge",
+        trace_id: "challenge",
+        emitted_at: Date.now(),
+        payload: { nonce: "nonce" },
+      }),
+    );
+    const connectFrame = transport.sent
+      .map((raw) => JSON.parse(raw))
+      .find((env) => env.event === "connect");
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "hello-ok",
+        trace_id: connectFrame.trace_id,
+        emitted_at: Date.now(),
+        payload: {},
+      }),
+    );
+    await Promise.resolve();
+
+    const duplicateFrame = {
+      version: "2",
+      event: "message.send",
+      trace_id: "dup-trace",
+      emitted_at: Date.now(),
+      chat_id: "chat-1",
+      chat_type: "direct",
+      sender: { id: "user-1", type: "direct", nick_name: "User" },
+      payload: {
+        message_id: "duplicate-message",
+        message_mode: "normal",
+        message: {
+          body: { fragments: [{ kind: "text", text: "hello" }] },
+          context: { mentions: [], reply: null },
+          streaming: {
+            status: "static",
+            sequence: 0,
+            mutation_policy: "sealed",
+            started_at: null,
+            completed_at: null,
+          },
+        },
+      },
+    };
+    transport.emitInbound(JSON.stringify(duplicateFrame));
+    transport.emitInbound(JSON.stringify({ ...duplicateFrame, trace_id: "dup-trace-2" }));
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    abortController.abort();
+    await run;
+
+    expect(claimMessageOnce).toHaveBeenCalledTimes(2);
+    expect(dispatchReplyFromConfig).toHaveBeenCalledTimes(1);
+  });
+
+  it("dispatches pending activation bootstrap through the normal direct inbound agent path after ready", async () => {
+    const capturedCtxs: Record<string, unknown>[] = [];
+    const resolveAgentRoute = vi.fn(() => ({
+      agentId: "default",
+      accountId: "default",
+      sessionKey: "session-from-route",
+    }));
+    const dispatchReplyFromConfig = vi.fn().mockResolvedValue({
+      counts: { final: 1, block: 0, tool: 0 },
+      queuedFinal: true,
+    });
+    const runtime = {
+      channel: {
+        routing: { resolveAgentRoute },
+        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: vi.fn((ctx: Record<string, unknown>) => {
+            capturedCtxs.push(ctx);
+            return ctx;
+          }),
+          resolveHumanDelayConfig: vi.fn(() => ({ enabled: false })),
+          createReplyDispatcherWithTyping: vi.fn(() => ({
+            dispatcher: {},
+            replyOptions: {},
+            markDispatchIdle: vi.fn(),
+            markRunComplete: vi.fn(),
+          })),
+          withReplyDispatcher: vi.fn(async (opts: { run: () => Promise<unknown> }) => opts.run()),
+          dispatchReplyFromConfig,
+        },
+        turn: {
+          buildContext: vi.fn((params) => {
+            const ctx = buildTestInboundContext(
+              params as Parameters<typeof buildTestInboundContext>[0],
+            );
+            capturedCtxs.push(ctx);
+            return ctx;
+          }),
+        },
+        media: {
+          fetchRemoteMedia: vi.fn(),
+          saveMediaBuffer: vi.fn(),
+          loadWebMedia: vi.fn(),
+        },
+      },
+    } as unknown as PluginRuntime;
+    const store = {
+      startConnection: vi.fn(() => 501),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+      claimMessageOnce: vi.fn(() => true),
+      claimPendingActivationBootstrap: vi.fn(() => ({ conversationId: "conv-activation" })),
+      markActivationBootstrapSent: vi.fn(() => true),
+      releaseActivationBootstrapClaim: vi.fn(() => true),
+    };
+
+    setOpenclawClawlingRuntime(runtime);
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+    const run = startOpenclawClawlingGateway({
+      cfg: {} as OpenClawConfig,
+      account: baseAccount({ token: "secret-token-value" }),
+      abortSignal: abortController.signal,
+      setStatus: vi.fn(),
+      getStatus: vi.fn(() => ({ connected: false, configured: true, running: true })),
+      log: { info: vi.fn(), error: vi.fn() },
+      transport,
+      store: store as NonNullable<Parameters<typeof startOpenclawClawlingGateway>[0]["store"]>,
+    });
+
+    await completeHandshake(transport, "challenge-bootstrap-1");
+    await new Promise((resolve) => setTimeout(resolve, 30));
+    abortController.abort();
+    await run;
+
+    expect(store.claimPendingActivationBootstrap).toHaveBeenCalledWith({
+      platform: "openclaw",
+      accountId: "default",
     });
-    expect(mapClawlingStateToStatus("connecting")).toMatchObject({
-      connected: false,
-      running: true,
+    expect(store.claimMessageOnce).toHaveBeenCalledWith(
+      expect.objectContaining({
+        platform: "openclaw",
+        accountId: "default",
+        kind: "message",
+        direction: "inbound",
+        eventType: "message.send",
+        chatId: "conv-activation",
+        messageId: expect.stringContaining("bootstrap"),
+      }),
+    );
+    expect(resolveAgentRoute).toHaveBeenCalledWith(
+      expect.objectContaining({ peer: { kind: "direct", id: "conv-activation" } }),
+    );
+    expect(capturedCtxs).toHaveLength(1);
+    const ctx = capturedCtxs[0]!;
+    const bodyForAgent = String(ctx.BodyForAgent);
+    expect(ctx.From).toBe("openclaw-clawchat:conv-activation");
+    expect(ctx.OriginatingTo).toBe("openclaw-clawchat:conv-activation");
+    expect(ctx.ChatType).toBe("direct");
+    expect(bodyForAgent).toBe(EXPECTED_ACTIVATION_BOOTSTRAP_TEXT);
+    expect(bodyForAgent).not.toContain("secret-token-value");
+    expect(dispatchReplyFromConfig).toHaveBeenCalledTimes(1);
+    expect(store.markActivationBootstrapSent).toHaveBeenCalledWith({
+      platform: "openclaw",
+      accountId: "default",
+      conversationId: "conv-activation",
     });
+    expect(dispatchReplyFromConfig.mock.invocationCallOrder[0]!).toBeLessThan(
+      store.markActivationBootstrapSent.mock.invocationCallOrder[0]!,
+    );
   });
 
-  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("does not repeat an activation bootstrap across reconnect while the first dispatch is in flight", async () => {
+    let resolveDispatch: (value: unknown) => void = () => {};
+    const dispatchReplyFromConfig = vi.fn(
+      () =>
+        new Promise((resolve) => {
+          resolveDispatch = resolve;
+        }),
+    );
+    const runtime = {
+      channel: {
+        routing: {
+          resolveAgentRoute: vi.fn(() => ({
+            agentId: "default",
+            accountId: "default",
+            sessionKey: "session-from-route",
+          })),
+        },
+        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: vi.fn((ctx: Record<string, unknown>) => ctx),
+          resolveHumanDelayConfig: vi.fn(() => ({ enabled: false })),
+          createReplyDispatcherWithTyping: vi.fn(() => ({
+            dispatcher: {},
+            replyOptions: {},
+            markDispatchIdle: vi.fn(),
+            markRunComplete: vi.fn(),
+          })),
+          withReplyDispatcher: vi.fn(async (opts: { run: () => Promise<unknown> }) => opts.run()),
+          dispatchReplyFromConfig,
+        },
+        turn: {
+          buildContext: vi.fn((params) =>
+            buildTestInboundContext(params as Parameters<typeof buildTestInboundContext>[0]),
+          ),
+        },
+        media: {
+          fetchRemoteMedia: vi.fn(),
+          saveMediaBuffer: vi.fn(),
+          loadWebMedia: vi.fn(),
+        },
+      },
+    } as unknown as PluginRuntime;
+    const store = {
+      startConnection: vi.fn(() => 601),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+      claimMessageOnce: vi.fn(() => true),
+      claimPendingActivationBootstrap: vi
+        .fn()
+        .mockReturnValueOnce({ conversationId: "conv-activation" })
+        .mockReturnValue(null),
+      markActivationBootstrapSent: vi.fn(() => true),
+      releaseActivationBootstrapClaim: vi.fn(() => true),
+    };
+    setOpenclawClawlingRuntime(runtime);
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+    const run = startOpenclawClawlingGateway({
+      cfg: {} as OpenClawConfig,
+      account: baseAccount({
+        reconnect: {
+          initialDelay: 1,
+          maxDelay: 1,
+          jitterRatio: 0,
+          maxRetries: Number.POSITIVE_INFINITY,
+        },
+      }),
+      abortSignal: abortController.signal,
+      setStatus: vi.fn(),
+      getStatus: vi.fn(() => ({ connected: false, configured: true, running: true })),
+      log: { info: vi.fn(), error: vi.fn() },
+      transport,
+      store: store as NonNullable<Parameters<typeof startOpenclawClawlingGateway>[0]["store"]>,
+    });
 
-  it("classifies generic errors as unknown", () => {
-    const c = classifyClawlingClientError(new Error("huh"));
-    expect(c.kind).toBe("unknown");
-    expect(c.retry).toBe(false);
+    await completeHandshake(transport, "challenge-bootstrap-first");
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    expect(dispatchReplyFromConfig).toHaveBeenCalledTimes(1);
+
+    transport.close(1006, "network lost");
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    await completeHandshake(transport, "challenge-bootstrap-reconnect");
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    expect(store.claimPendingActivationBootstrap).toHaveBeenCalledTimes(2);
+    expect(dispatchReplyFromConfig).toHaveBeenCalledTimes(1);
+
+    resolveDispatch({ counts: { final: 1, block: 0, tool: 0 }, queuedFinal: true });
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    abortController.abort();
+    await run;
+
+    expect(store.markActivationBootstrapSent).toHaveBeenCalledTimes(1);
+    expect(store.markActivationBootstrapSent).toHaveBeenCalledWith({
+      platform: "openclaw",
+      accountId: "default",
+      conversationId: "conv-activation",
+    });
   });
 
-  it("runtime store round-trips", () => {
-    const rt = { mocked: true } as unknown as PluginRuntime;
-    setOpenclawClawlingRuntime(rt);
-    expect(getOpenclawClawlingRuntime()).toBe(rt);
+  it("releases an activation bootstrap claim when agent submission fails", async () => {
+    const dispatchReplyFromConfig = vi.fn().mockRejectedValue(new Error("dispatch failed"));
+    const runtime = {
+      channel: {
+        routing: {
+          resolveAgentRoute: vi.fn(() => ({
+            agentId: "default",
+            accountId: "default",
+            sessionKey: "session-from-route",
+          })),
+        },
+        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: vi.fn((ctx: Record<string, unknown>) => ctx),
+          resolveHumanDelayConfig: vi.fn(() => ({ enabled: false })),
+          createReplyDispatcherWithTyping: vi.fn(() => ({
+            dispatcher: {},
+            replyOptions: {},
+            markDispatchIdle: vi.fn(),
+            markRunComplete: vi.fn(),
+          })),
+          withReplyDispatcher: vi.fn(async (opts: { run: () => Promise<unknown> }) => opts.run()),
+          dispatchReplyFromConfig,
+        },
+        turn: {
+          buildContext: vi.fn((params) =>
+            buildTestInboundContext(params as Parameters<typeof buildTestInboundContext>[0]),
+          ),
+        },
+        media: {
+          fetchRemoteMedia: vi.fn(),
+          saveMediaBuffer: vi.fn(),
+          loadWebMedia: vi.fn(),
+        },
+      },
+    } as unknown as PluginRuntime;
+    const store = {
+      startConnection: vi.fn(() => 701),
+      markConnectSent: vi.fn(),
+      markConnectionReady: vi.fn(),
+      finishConnection: vi.fn(),
+      claimMessageOnce: vi.fn(() => true),
+      claimPendingActivationBootstrap: vi.fn(() => ({ conversationId: "conv-activation" })),
+      markActivationBootstrapSent: vi.fn(() => true),
+      releaseActivationBootstrapClaim: vi.fn(() => true),
+    };
+    setOpenclawClawlingRuntime(runtime);
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+    const run = startOpenclawClawlingGateway({
+      cfg: {} as OpenClawConfig,
+      account: baseAccount(),
+      abortSignal: abortController.signal,
+      setStatus: vi.fn(),
+      getStatus: vi.fn(() => ({ connected: false, configured: true, running: true })),
+      log: { info: vi.fn(), error: vi.fn() },
+      transport,
+      store: store as NonNullable<Parameters<typeof startOpenclawClawlingGateway>[0]["store"]>,
+    });
+
+    await completeHandshake(transport, "challenge-bootstrap-failure");
+    await new Promise((resolve) => setTimeout(resolve, 30));
+    abortController.abort();
+    await run;
+
+    expect(dispatchReplyFromConfig).toHaveBeenCalledTimes(1);
+    expect(store.markActivationBootstrapSent).not.toHaveBeenCalled();
+    expect(store.releaseActivationBootstrapClaim).toHaveBeenCalledWith({
+      platform: "openclaw",
+      accountId: "default",
+      conversationId: "conv-activation",
+    });
   });
-});
 
-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 buildContext = vi.fn((params: Parameters<PluginRuntime["channel"]["turn"]["buildContext"]>[0]) => {
+      capturedCtx = buildTestInboundContext(params as Parameters<typeof buildTestInboundContext>[0]);
+      return capturedCtx as ReturnType<PluginRuntime["channel"]["turn"]["buildContext"]>;
     });
     const resolveAgentRoute = vi.fn(() => ({
       agentId: "u",
@@ -77,7 +1985,7 @@ describe("openclaw-clawchat runtime media ingest", () => {
         reply: {
           formatAgentEnvelope: vi.fn((p: { body: string }) => p.body),
           resolveEnvelopeFormatOptions: vi.fn(() => ({})),
-          finalizeInboundContext,
+          finalizeInboundContext: vi.fn((ctx: Record<string, unknown>) => ctx),
           resolveHumanDelayConfig: vi.fn(() => ({ enabled: false })),
           createReplyDispatcherWithTyping: vi.fn(() => ({
             dispatcher: {},
@@ -90,6 +1998,9 @@ describe("openclaw-clawchat runtime media ingest", () => {
           }),
           dispatchReplyFromConfig: vi.fn().mockResolvedValue(undefined),
         },
+        turn: {
+          buildContext,
+        },
         media: {
           fetchRemoteMedia: vi.fn(async ({ url }: { url: string }) => {
             fetched.push({ url });
@@ -107,7 +2018,7 @@ describe("openclaw-clawchat runtime media ingest", () => {
     setOpenclawClawlingRuntime(runtime);
 
     const { startOpenclawClawlingGateway } = await import("./runtime.ts");
-    const { MockTransport } = await import("@newbase-clawchat/sdk");
+    const { MockTransport } = await import("./mock-transport.ts");
     const transport = new MockTransport();
     const abortController = new AbortController();
 
@@ -153,11 +2064,14 @@ describe("openclaw-clawchat runtime media ingest", () => {
         payload: { nonce: "n" },
       }),
     );
+    const connectFrame = transport.sent
+      .map((raw) => JSON.parse(raw))
+      .find((env) => env.event === "connect");
     transport.emitInbound(
       JSON.stringify({
         version: "2",
         event: "hello-ok",
-        trace_id: "th",
+        trace_id: connectFrame.trace_id,
         emitted_at: Date.now(),
         payload: {},
       }),
@@ -173,7 +2087,7 @@ describe("openclaw-clawchat runtime media ingest", () => {
         chat_id: "chat-1",
         chat_type: "direct",
         to: { id: "u", type: "direct" },
-        sender: { sender_id: "user-1", type: "direct", display_name: "User" },
+        sender: { id: "user-1", type: "direct", nick_name: "User" },
         payload: {
           message_id: "m-with-image",
           message_mode: "normal",
@@ -192,7 +2106,6 @@ describe("openclaw-clawchat runtime media ingest", () => {
               started_at: null,
               completed_at: null,
             },
-            sender: { sender_id: "user-1", type: "direct", display_name: "User" },
           },
         },
       }),
@@ -205,7 +2118,14 @@ describe("openclaw-clawchat runtime media ingest", () => {
     expect(capturedCtx?.MediaPath).toBe("/cache/1.png");
     expect(capturedCtx?.MediaPaths).toEqual(["/cache/1.png"]);
     expect(capturedCtx?.From).toBe("openclaw-clawchat:chat-1");
+    expect(capturedCtx?.OriginatingTo).toBe("openclaw-clawchat:chat-1");
     expect(capturedCtx?.ConversationLabel).toBe("chat-1");
+    expect(capturedCtx?.GroupSystemPrompt).toBeUndefined();
+    const directBuildContextArg = buildContext.mock.calls[0]?.[0] as
+      | Parameters<PluginRuntime["channel"]["turn"]["buildContext"]>[0]
+      | undefined;
+    expect(directBuildContextArg?.conversation.kind).toBe("direct");
+    expect(directBuildContextArg?.supplemental).toBeUndefined();
     expect(capturedCtx?.SenderId).toBe("user-1");
     expect(resolveAgentRoute).toHaveBeenCalledWith(
       expect.objectContaining({
@@ -223,9 +2143,13 @@ describe("openclaw-clawchat runtime media ingest", () => {
 
   it("uses group chat_id as the canonical conversation identity", async () => {
     let capturedCtx: Record<string, unknown> | undefined;
-    const finalizeInboundContext = vi.fn((ctx: Record<string, unknown>) => {
-      capturedCtx = ctx;
-      return ctx;
+    const buildContext = vi.fn((params: Parameters<PluginRuntime["channel"]["turn"]["buildContext"]>[0]) => {
+      capturedCtx = buildTestInboundContext(params as Parameters<typeof buildTestInboundContext>[0]);
+      return capturedCtx as ReturnType<PluginRuntime["channel"]["turn"]["buildContext"]>;
+    });
+    const dispatchReplyFromConfig = vi.fn().mockResolvedValue({
+      counts: { final: 1, block: 0, tool: 0 },
+      queuedFinal: true,
     });
 
     const runtime = {
@@ -244,7 +2168,7 @@ describe("openclaw-clawchat runtime media ingest", () => {
         reply: {
           formatAgentEnvelope: vi.fn((p: { body: string }) => p.body),
           resolveEnvelopeFormatOptions: vi.fn(() => ({})),
-          finalizeInboundContext,
+          finalizeInboundContext: vi.fn((ctx: Record<string, unknown>) => ctx),
           resolveHumanDelayConfig: vi.fn(() => ({ enabled: false })),
           createReplyDispatcherWithTyping: vi.fn(() => ({
             dispatcher: {},
@@ -255,7 +2179,10 @@ describe("openclaw-clawchat runtime media ingest", () => {
           withReplyDispatcher: vi.fn(async (opts: { run: () => Promise<unknown> }) => {
             await opts.run();
           }),
-          dispatchReplyFromConfig: vi.fn().mockResolvedValue(undefined),
+          dispatchReplyFromConfig,
+        },
+        turn: {
+          buildContext,
         },
         media: {
           fetchRemoteMedia: vi.fn(),
@@ -284,8 +2211,10 @@ describe("openclaw-clawchat runtime media ingest", () => {
         userId: "u",
         replyMode: "static",
         groupMode: "all",
+        groups: {},
         forwardThinking: true,
         forwardToolCalls: false,
+        richInteractions: false,
         allowFrom: [],
         stream: { flushIntervalMs: 250, minChunkChars: 40, maxBufferChars: 2000 },
         reconnect: {
@@ -314,11 +2243,14 @@ describe("openclaw-clawchat runtime media ingest", () => {
         payload: { nonce: "n" },
       }),
     );
+    const connectFrame = transport.sent
+      .map((raw) => JSON.parse(raw))
+      .find((env) => env.event === "connect");
     transport.emitInbound(
       JSON.stringify({
         version: "2",
         event: "hello-ok",
-        trace_id: "th",
+        trace_id: connectFrame.trace_id,
         emitted_at: Date.now(),
         payload: {},
       }),
@@ -334,7 +2266,7 @@ describe("openclaw-clawchat runtime media ingest", () => {
         chat_id: "grp-1",
         chat_type: "group",
         to: { id: "u", type: "group" },
-        sender: { sender_id: "user-1", type: "group", display_name: "Alice" },
+        sender: { id: "user-1", type: "direct", nick_name: "Alice" },
         payload: {
           message_id: "m-group",
           message_mode: "normal",
@@ -359,9 +2291,143 @@ describe("openclaw-clawchat runtime media ingest", () => {
     await startPromise;
 
     expect(capturedCtx?.From).toBe("openclaw-clawchat:group:grp-1");
+    expect(capturedCtx?.OriginatingTo).toBe("openclaw-clawchat:group:grp-1");
     expect(capturedCtx?.ConversationLabel).toBe("group:grp-1");
     expect(capturedCtx?.SenderId).toBe("user-1");
     expect(capturedCtx?.ChatType).toBe("group");
+    expect(capturedCtx?.GroupSystemPrompt).toBe(EXPECTED_CLAWCHAT_GROUP_SYSTEM_PROMPT);
+    const groupBuildContextArg = buildContext.mock.calls[0]?.[0] as
+      | Parameters<PluginRuntime["channel"]["turn"]["buildContext"]>[0]
+      | undefined;
+    expect(groupBuildContextArg?.conversation.kind).toBe("group");
+    expect(groupBuildContextArg?.supplemental?.groupSystemPrompt).toBe(
+      EXPECTED_CLAWCHAT_GROUP_SYSTEM_PROMPT,
+    );
+    expect(dispatchReplyFromConfig).toHaveBeenCalledWith(
+      expect.objectContaining({
+        replyOptions: expect.objectContaining({
+          sourceReplyDeliveryMode: "automatic",
+        }),
+      }),
+    );
+  });
+
+  it("dispatches completed message.done frames to the OpenClaw agent path", async () => {
+    const dispatchReplyFromConfig = vi.fn().mockResolvedValue({
+      counts: { final: 1, block: 0, tool: 0 },
+      queuedFinal: true,
+    });
+    const runtime = {
+      channel: {
+        routing: {
+          resolveAgentRoute: vi.fn(() => ({
+            agentId: "default",
+            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: vi.fn((ctx: Record<string, unknown>) => ctx),
+          resolveHumanDelayConfig: vi.fn(() => ({ enabled: false })),
+          createReplyDispatcherWithTyping: vi.fn(() => ({
+            dispatcher: {},
+            replyOptions: {},
+            markDispatchIdle: vi.fn(),
+            markRunComplete: vi.fn(),
+          })),
+          withReplyDispatcher: vi.fn(
+            async (opts: { run: () => Promise<unknown>; onSettled?: () => void | Promise<void> }) => {
+              try {
+                return await opts.run();
+              } finally {
+                await opts.onSettled?.();
+              }
+            },
+          ),
+          dispatchReplyFromConfig,
+        },
+        turn: {
+          buildContext: vi.fn((params) =>
+            buildTestInboundContext(params as Parameters<typeof buildTestInboundContext>[0]),
+          ),
+        },
+        media: {
+          fetchRemoteMedia: vi.fn(),
+          saveMediaBuffer: vi.fn(),
+          loadWebMedia: vi.fn(),
+        },
+      },
+    } as unknown as PluginRuntime;
+    setOpenclawClawlingRuntime(runtime);
+    const transport = new MockTransport();
+    const abortController = new AbortController();
+
+    const run = startOpenclawClawlingGateway({
+      cfg: {},
+      account: baseAccount(),
+      abortSignal: abortController.signal,
+      setStatus: vi.fn(),
+      getStatus: vi.fn(() => ({ connected: false, configured: true, running: true })),
+      log: { info: vi.fn(), error: vi.fn() },
+      transport,
+    });
+
+    await Promise.resolve();
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "connect.challenge",
+        trace_id: "challenge",
+        emitted_at: Date.now(),
+        payload: { nonce: "nonce" },
+      }),
+    );
+    const connectFrame = transport.sent
+      .map((raw) => JSON.parse(raw))
+      .find((env) => env.event === "connect");
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "hello-ok",
+        trace_id: connectFrame.trace_id,
+        emitted_at: Date.now(),
+        payload: {},
+      }),
+    );
+    await Promise.resolve();
+    transport.emitInbound(
+      JSON.stringify({
+        version: "2",
+        event: "message.done",
+        trace_id: "done-1",
+        emitted_at: Date.now(),
+        chat_id: "chat-1",
+        chat_type: "direct",
+        sender: { id: "user-1", type: "direct", nick_name: "User" },
+        payload: {
+          message_id: "stream-1",
+          fragments: [{ kind: "text", text: "completed stream" }],
+          streaming: {
+            status: "done",
+            sequence: 1,
+            mutation_policy: "append_text_only",
+            started_at: null,
+            completed_at: Date.now(),
+          },
+        },
+      }),
+    );
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    abortController.abort();
+    await run;
+
+    expect(dispatchReplyFromConfig).toHaveBeenCalledTimes(1);
   });
 });
 
@@ -406,6 +2472,11 @@ describe("openclaw-clawchat runtime reply dispatch lifecycle", () => {
           withReplyDispatcher,
           dispatchReplyFromConfig,
         },
+        turn: {
+          buildContext: vi.fn((params) =>
+            buildTestInboundContext(params as Parameters<typeof buildTestInboundContext>[0]),
+          ),
+        },
         media: {
           fetchRemoteMedia: vi.fn(),
           saveMediaBuffer: vi.fn(),
@@ -462,11 +2533,14 @@ describe("openclaw-clawchat runtime reply dispatch lifecycle", () => {
         payload: { nonce: "n" },
       }),
     );
+    const connectFrame = transport.sent
+      .map((raw) => JSON.parse(raw))
+      .find((env) => env.event === "connect");
     transport.emitInbound(
       JSON.stringify({
         version: "2",
         event: "hello-ok",
-        trace_id: "th",
+        trace_id: connectFrame.trace_id,
         emitted_at: Date.now(),
         payload: {},
       }),
@@ -482,7 +2556,7 @@ describe("openclaw-clawchat runtime reply dispatch lifecycle", () => {
         chat_id: "chat-1",
         chat_type: "direct",
         to: { id: "u", type: "direct" },
-        sender: { sender_id: "user-1", type: "direct", display_name: "User" },
+        sender: { id: "user-1", type: "direct", nick_name: "User" },
         payload: {
           message_id: "m-fail",
           message_mode: "normal",
@@ -512,6 +2586,8 @@ describe("openclaw-clawchat runtime reply dispatch lifecycle", () => {
     expect(logError).toHaveBeenCalledWith(
       expect.stringContaining("openclaw-clawchat dispatch failed msg=m-fail"),
     );
+    const sentEvents = transport.sent.map((wire) => JSON.parse(wire) as { event: string });
+    expect(sentEvents.filter((event) => event.event === "message.send")).toEqual([]);
   });
 });
 
@@ -569,11 +2645,14 @@ describe("openclaw-clawchat runtime connect flow", () => {
         payload: { nonce: "n1" },
       }),
     );
+    const connectFrame = transport.sent
+      .map((raw) => JSON.parse(raw))
+      .find((env) => env.event === "connect");
     transport.emitInbound(
       JSON.stringify({
         version: "2",
         event: "hello-ok",
-        trace_id: "t2",
+        trace_id: connectFrame.trace_id,
         emitted_at: Date.now(),
         payload: {},
       }),