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

package/src/protocol-types.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, expectTypeOf, it } from "vitest";
+import {
+  EVENT,
+  isBusinessDispatchEvent,
+  type Envelope,
+  type Fragment,
+  type MessagePayload,
+  type ProtocolFragment,
+  type Sender,
+  type StreamDonePayload,
+} from "./protocol-types.ts";
+
+describe("clawchat local protocol types", () => {
+  it("declares protocol v2 event constants used by runtime dispatch", () => {
+    expect(EVENT.MESSAGE_SEND).toBe("message.send");
+    expect(EVENT.MESSAGE_REPLY).toBe("message.reply");
+    expect(EVENT.MESSAGE_DONE).toBe("message.done");
+    expect(EVENT.TYPING_UPDATE).toBe("typing.update");
+    expect(EVENT.PING).toBe("ping");
+    expect(EVENT.PONG).toBe("pong");
+  });
+
+  it("treats message.send, message.reply, and message.done as agent-dispatch events", () => {
+    expect(isBusinessDispatchEvent(EVENT.MESSAGE_SEND)).toBe(true);
+    expect(isBusinessDispatchEvent(EVENT.MESSAGE_REPLY)).toBe(true);
+    expect(isBusinessDispatchEvent(EVENT.MESSAGE_DONE)).toBe(true);
+    expect(isBusinessDispatchEvent(EVENT.MESSAGE_ADD)).toBe(false);
+    expect(isBusinessDispatchEvent(EVENT.PONG)).toBe(false);
+  });
+
+  it("models typing.update with is_typing payload", () => {
+    const env: Envelope<{ is_typing: boolean }> = {
+      version: "2",
+      event: EVENT.TYPING_UPDATE,
+      trace_id: "trace-typing",
+      emitted_at: 1776162600000,
+      chat_id: "chat-1",
+      payload: { is_typing: true },
+    };
+    expect(env.payload.is_typing).toBe(true);
+  });
+
+  it("models sender as a downlink user shape with required direct type", () => {
+    expectTypeOf<Sender["type"]>().toEqualTypeOf<"direct">();
+  });
+
+  it("models materialized message payloads with optional uplink message IDs", () => {
+    expectTypeOf<{
+      message_mode: string;
+      message: MessagePayload["message"];
+    }>().toMatchTypeOf<MessagePayload>();
+  });
+
+  it("models reply previews with required identity and local fragments", () => {
+    type ReplyContext = NonNullable<MessagePayload["message"]["context"]["reply"]>;
+    type ReplyPreview = NonNullable<ReplyContext["reply_preview"]>;
+
+    expectTypeOf<ReplyPreview["id"]>().toEqualTypeOf<string>();
+    expectTypeOf<ReplyPreview["nick_name"]>().toEqualTypeOf<string>();
+    expectTypeOf<ReplyPreview["fragments"]>().toEqualTypeOf<Fragment[]>();
+  });
+
+  it("uses local fragments for message bodies and flat stream completion payloads", () => {
+    expectTypeOf<Fragment>().toMatchTypeOf<ProtocolFragment>();
+    expectTypeOf<MessagePayload["message"]["body"]["fragments"]>().toEqualTypeOf<Fragment[]>();
+    expectTypeOf<StreamDonePayload["fragments"]>().toEqualTypeOf<Fragment[]>();
+    expectTypeOf<StreamDonePayload>().not.toHaveProperty("message");
+  });
+});

package/src/protocol-types.ts

@@ -0,0 +1,296 @@
+export const EVENT = {
+  CONNECT_CHALLENGE: "connect.challenge",
+  CONNECT: "connect",
+  HELLO_OK: "hello-ok",
+  HELLO_FAIL: "hello-fail",
+  MESSAGE_SEND: "message.send",
+  MESSAGE_ACK: "message.ack",
+  MESSAGE_ERROR: "message.error",
+  MESSAGE_REPLY: "message.reply",
+  MESSAGE_CREATED: "message.created",
+  MESSAGE_ADD: "message.add",
+  MESSAGE_DONE: "message.done",
+  MESSAGE_FAILED: "message.failed",
+  TYPING_UPDATE: "typing.update",
+  CHAT_METADATA_INVALIDATED: "chat.metadata.invalidated",
+  OFFLINE_BATCH: "offline.batch",
+  OFFLINE_ACK: "offline.ack",
+  OFFLINE_DONE: "offline.done",
+  PING: "ping",
+  PONG: "pong",
+} as const;
+
+export type KnownEventName = typeof EVENT[keyof typeof EVENT];
+export type EventName = KnownEventName | string;
+export type ChatType = "direct" | "group";
+export type ConnState =
+  | "idle"
+  | "connecting"
+  | "challenging"
+  | "authenticating"
+  | "connected"
+  | "reconnecting"
+  | "disconnected";
+export type TransportState = "closed" | "connecting" | "open";
+
+export interface TransportEvents {
+  onOpen: () => void;
+  onMessage: (data: string | Buffer) => void;
+  onClose: (code: number, reason: string) => void;
+  onError: (err: Error) => void;
+}
+
+export interface Transport {
+  readonly state: TransportState;
+  connect(url: string, handlers: TransportEvents): Promise<void>;
+  send(data: string): void;
+  close(code?: number, reason?: string): void;
+}
+
+export interface Routing {
+  id: string;
+  type: ChatType;
+}
+
+export interface Sender {
+  id: string;
+  type: "direct";
+  nick_name: string;
+}
+
+export interface Envelope<TPayload = unknown> {
+  version: "2";
+  event: EventName;
+  trace_id: string;
+  emitted_at: number;
+  chat_id?: string;
+  chat_type?: ChatType;
+  to?: Routing;
+  sender?: Sender;
+  payload: TPayload;
+}
+
+export interface ChallengePayload {
+  nonce: string;
+}
+
+export interface ConnectCapabilities {
+  multi_device?: boolean;
+  device_replay?: boolean;
+  chat_meta_events?: boolean;
+}
+
+export interface ConnectPayload {
+  token: string;
+  nonce: string;
+  device_id?: string;
+  capabilities?: ConnectCapabilities;
+}
+
+export interface HelloOKPayload {
+  device_id?: string;
+  delivery_mode?: string;
+}
+
+export interface HelloFailPayload {
+  reason: string;
+}
+
+export interface TextFragment {
+  kind: "text";
+  text: string;
+  delta?: string;
+}
+
+export interface MentionFragment {
+  kind: "mention";
+  user_id: string;
+  display?: string;
+}
+
+export interface ImageFragment {
+  kind: "image";
+  url: string;
+  name?: string;
+  mime?: string;
+  size?: number;
+  width?: number;
+  height?: number;
+}
+
+export interface FileFragment {
+  kind: "file";
+  url: string;
+  name?: string;
+  mime?: string;
+  size?: number;
+}
+
+export interface AudioFragment {
+  kind: "audio";
+  url: string;
+  name?: string;
+  mime?: string;
+  size?: number;
+  duration?: number;
+}
+
+export interface VideoFragment {
+  kind: "video";
+  url: string;
+  name?: string;
+  mime?: string;
+  size?: number;
+  width?: number;
+  height?: number;
+  duration?: number;
+}
+
+export type Fragment =
+  | TextFragment
+  | MentionFragment
+  | ImageFragment
+  | FileFragment
+  | AudioFragment
+  | VideoFragment;
+
+export interface UnknownFragment {
+  kind: string;
+  [field: string]: unknown;
+}
+
+export type ProtocolFragment = Fragment | UnknownFragment;
+
+export interface Streaming {
+  status: "static" | "streaming" | "done" | "failed" | (string & {});
+  sequence: number;
+  mutation_policy: "sealed" | "append_text_only" | (string & {});
+  started_at?: number | null;
+  completed_at?: number | null;
+}
+
+export interface MessageContext {
+  mentions: unknown[];
+  reply: {
+    reply_to_msg_id: string;
+    reply_preview: {
+      id: string;
+      nick_name: string;
+      fragments: Fragment[];
+    } | null;
+  } | null;
+}
+
+export interface MessagePayload {
+  message_id?: string;
+  message_mode: string;
+  message: {
+    body: { fragments: Fragment[] };
+    context: MessageContext;
+    streaming?: Streaming;
+  };
+}
+
+export interface MessageAckPayload {
+  message_id: string;
+  accepted_at: number;
+}
+
+export interface MessageErrorPayload {
+  code: string;
+  message: string;
+}
+
+export interface ChatMetadataInvalidatedPayload {
+  scope?: string[];
+  version?: number;
+  updated_at?: number;
+}
+
+export interface StreamCreatedPayload {
+  message_id: string;
+  message_mode?: string;
+}
+
+export interface Mutation {
+  type: string;
+  target_fragment_index: number | null;
+}
+
+export interface StreamAddPayload {
+  message_id: string;
+  sequence: number;
+  mutation?: Mutation | null;
+  fragments: Fragment[];
+  streaming?: Streaming;
+  added_at?: number;
+}
+
+export interface StreamDonePayload {
+  message_id: string;
+  fragments: Fragment[];
+  streaming?: Streaming;
+  completed_at?: number;
+}
+
+export type StreamFailedPayload = StreamDonePayload;
+
+export interface OfflineBatchPayload {
+  batch_id: number;
+  items: Envelope[];
+  remaining: number;
+}
+
+export interface OfflineAckPayload {
+  batch_id: number;
+}
+
+export type OfflineDonePayload = Record<string, never>;
+
+export type EmptyPayload = Record<string, never>;
+
+export interface TypingUpdatePayload {
+  is_typing: boolean;
+}
+
+export class AuthError extends Error {
+  override name = "AuthError";
+}
+
+export class TransportError extends Error {
+  override name = "TransportError";
+}
+
+export class ProtocolError extends Error {
+  override name = "ProtocolError";
+  constructor(message: string, readonly envelope?: unknown) {
+    super(message);
+  }
+}
+
+export class AckTimeoutError extends Error {
+  override name = "AckTimeoutError";
+  constructor(readonly traceId: string, readonly timeoutMs: number) {
+    super(`ack timeout after ${timeoutMs}ms for trace_id=${traceId}`);
+  }
+}
+
+export class MessageSendError extends Error {
+  override name = "MessageSendError";
+  constructor(
+    readonly traceId: string,
+    readonly code: string,
+    message: string,
+    readonly chatId?: string,
+  ) {
+    super(`message.error ${code}: ${message} for trace_id=${traceId}`);
+  }
+}
+
+export class StateError extends Error {
+  override name = "StateError";
+}
+
+export function isBusinessDispatchEvent(event: string): boolean {
+  return event === EVENT.MESSAGE_SEND || event === EVENT.MESSAGE_REPLY || event === EVENT.MESSAGE_DONE;
+}

package/src/protocol-types.typecheck.ts

@@ -0,0 +1,89 @@
+import type {
+  ConnectPayload,
+  EmptyPayload,
+  Envelope,
+  Fragment,
+  MessagePayload,
+  OfflineBatchPayload,
+  ProtocolFragment,
+  Sender,
+  StreamAddPayload,
+  StreamDonePayload,
+} from "./protocol-types.ts";
+
+type Assert<T extends true> = T;
+type IsAssignable<From, To> = [From] extends [To] ? true : false;
+type IsEqual<Actual, Expected> =
+  (<T>() => T extends Actual ? 1 : 2) extends <T>() => T extends Expected ? 1 : 2
+    ? true
+    : false;
+type Not<T extends boolean> = T extends true ? false : true;
+
+type _SenderRequiresType = Assert<
+  Not<IsAssignable<{ id: string; nick_name: string }, Sender>>
+>;
+
+type _MaterializedMessageIdMayBeOmittedOnUplink = Assert<
+  IsAssignable<
+    { message_mode: string; message: MessagePayload["message"] },
+    MessagePayload
+  >
+>;
+
+type _KnownTextFragmentRequiresText = Assert<
+  Not<IsAssignable<{ kind: "text" }, Fragment>>
+>;
+
+type _KnownMentionFragmentRequiresUserId = Assert<
+  Not<IsAssignable<{ kind: "mention" }, Fragment>>
+>;
+
+type _UnknownWireFragmentsAreRepresentable = Assert<
+  IsAssignable<{ kind: "sticker"; sticker_id: string }, ProtocolFragment>
+>;
+
+type _MaterializedMessageBodyUsesWireFragments = Assert<
+  IsEqual<MessagePayload["message"]["body"]["fragments"], Fragment[]>
+>;
+
+type _MaterializedMessageRejectsMalformedKnownFragments = Assert<
+  Not<
+    IsAssignable<
+      {
+        message_mode: string;
+        message: {
+          body: { fragments: [{ kind: "text" }] };
+          context: MessagePayload["message"]["context"];
+        };
+      },
+      MessagePayload
+    >
+  >
+>;
+
+type _StreamCompletionUsesWireFragments = Assert<
+  IsEqual<StreamDonePayload["fragments"], Fragment[]>
+>;
+
+type _StreamCompletionPayloadIsFlat = Assert<
+  Not<"message" extends keyof StreamDonePayload ? true : false>
+>;
+
+type _ConnectPayloadAllowsCanonicalMinimum = Assert<
+  IsAssignable<{ token: string; nonce: string }, ConnectPayload>
+>;
+
+type _StreamAddPayloadAllowsCanonicalMinimum = Assert<
+  IsAssignable<
+    { message_id: string; sequence: number; fragments: Fragment[] },
+    StreamAddPayload
+  >
+>;
+
+type _OfflineBatchPayloadCarriesEnvelopes = Assert<
+  IsAssignable<{ batch_id: number; items: Envelope[]; remaining: number }, OfflineBatchPayload>
+>;
+
+type _ControlPayloadsAreEmptyObjects = Assert<
+  IsAssignable<Record<string, never>, EmptyPayload>
+>;

package/src/protocol.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { isInboundMessagePayload, isGroupSender, hasRenderableText } from "./protocol.ts";
+import { isInboundMessagePayload, hasRenderableText } from "./protocol.ts";
 
 describe("openclaw-clawchat protocol guards", () => {
   it("accepts a well-formed downlink message payload", () => {
@@ -29,11 +29,6 @@ describe("openclaw-clawchat protocol guards", () => {
     expect(isInboundMessagePayload({ message_id: "m1" })).toBe(false);
   });
 
-  it("detects group sender", () => {
-    expect(isGroupSender({ sender_id: "g", type: "group", display_name: "Group" })).toBe(true);
-    expect(isGroupSender({ sender_id: "u", type: "direct", display_name: "User" })).toBe(false);
-  });
-
   it("detects renderable text", () => {
     expect(hasRenderableText({ body: { fragments: [{ kind: "text", text: "hi" }] } })).toBe(true);
     expect(hasRenderableText({ body: { fragments: [{ kind: "image", url: "x" }] } })).toBe(true);

package/src/protocol.ts

@@ -1,8 +1,8 @@
 /**
  * Local narrow guards for inbound protocol envelopes.
  *
- * The SDK's `message` event hands us `Envelope<unknown>`. Before casting the
- * payload to `DownlinkMessageSendPayload` we run these cheap structural checks
+ * Raw client events hand us `Envelope<unknown>`. Before casting the
+ * payload to `MessagePayload` we run these cheap structural checks
  * so runtime errors surface as skipped messages, not crashes.
  */
 
@@ -40,8 +40,3 @@ export function hasRenderableText(message: {
           (f as { url: string }).url.trim().length > 0)),
   );
 }
-
-export function isGroupSender(sender: unknown): boolean {
-  if (!sender || typeof sender !== "object") return false;
-  return (sender as { type?: unknown }).type === "group";
-}