@clawling/clawchat-plugin-openclaw 2026.5.12-28

package/src/profile-sync.ts

@@ -0,0 +1,191 @@
+import type { ConversationDetails, Profile } from "./api-types.ts";
+import {
+  pullGroupMetadata,
+  pullOwnerMetadata,
+  pullUserMetadata,
+} from "./clawchat-metadata.ts";
+
+type ProfileSyncApi = {
+  getConversation?: (conversationId: string) => Promise<{ conversation: ConversationDetails }>;
+  getUserInfo?: (userId: string) => Promise<Profile>;
+  getUserProfile?: (userId: string) => Promise<Profile>;
+  getAgentDetail?: (agentId: string) => Promise<{ agent: unknown }>;
+  getAgentProfile?: (agentId: string) => Promise<{ agent: unknown }>;
+};
+
+type ProfileSyncStore = {
+  readonly __conversationCacheRemoved?: true;
+};
+
+function requireMemoryRoot(
+  memoryRoot: string | undefined,
+  log: { error?: (message: string) => void } | undefined,
+  label: string,
+): memoryRoot is string {
+  if (typeof memoryRoot === "string" && memoryRoot.trim()) return true;
+  log?.error?.(`clawchat-plugin-openclaw ${label} metadata refresh requires memoryRoot`);
+  return false;
+}
+
+export async function ensureUserProfileForSender(params: {
+  platform: string;
+  accountId: string;
+  accountUserId: string;
+  accountOwnerUserId: string;
+  sender: { id: string; nickname?: string | null };
+  lastSeenAt?: number | null;
+  api: ProfileSyncApi;
+  store: ProfileSyncStore;
+  memoryRoot?: string;
+  log?: { error?: (message: string) => void };
+}): Promise<void> {
+  void params.accountUserId;
+  void params.accountOwnerUserId;
+  void params.lastSeenAt;
+  void params.sender.nickname;
+  if (!requireMemoryRoot(params.memoryRoot, params.log, "user")) return;
+  try {
+    await pullUserMetadata({
+      memoryRoot: params.memoryRoot,
+      userId: params.sender.id,
+      api: params.api,
+    });
+  } catch (err) {
+    params.log?.error?.(
+      `clawchat-plugin-openclaw first-seen user metadata refresh failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
+
+export async function refreshGroupProfile(params: {
+  platform: string;
+  accountId: string;
+  accountUserId?: string;
+  accountOwnerUserId?: string;
+  chatId?: string;
+  conversationId?: string;
+  metadataVersion?: number;
+  api: ProfileSyncApi;
+  store: ProfileSyncStore;
+  memoryRoot?: string;
+  log?: { error?: (message: string) => void };
+}): Promise<boolean> {
+  const conversationId = params.conversationId ?? params.chatId ?? "";
+  if (!conversationId || !params.api.getConversation) return false;
+  try {
+    if (requireMemoryRoot(params.memoryRoot, params.log, "group")) {
+      const result = await pullGroupMetadata({
+        memoryRoot: params.memoryRoot,
+        groupId: conversationId,
+        api: params.api,
+        skipUserIds: [params.accountUserId, params.accountOwnerUserId],
+      });
+      if (result.failures.length > 0) {
+        params.log?.error?.(
+          `clawchat-plugin-openclaw group participant metadata refresh partially failed: ${result.failures.map((failure) => `${failure.targetId}: ${failure.error}`).join("; ")}`,
+        );
+      }
+      if (!result.conversation) return false;
+    } else {
+      await params.api.getConversation(conversationId);
+    }
+    return true;
+  } catch (err) {
+    params.log?.error?.(
+      `clawchat-plugin-openclaw group metadata refresh failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return false;
+  }
+}
+
+export async function ensureGroupProfileForChat(params: {
+  platform: string;
+  accountId: string;
+  accountUserId?: string;
+  accountOwnerUserId?: string;
+  chat: { id: string; type: "direct" | "group"; lastSeenAt?: number | null };
+  api: ProfileSyncApi;
+  store: ProfileSyncStore;
+  memoryRoot?: string;
+  log?: { error?: (message: string) => void };
+}): Promise<boolean> {
+  if (params.chat.type !== "group") return false;
+  return await refreshGroupProfile({
+    platform: params.platform,
+    accountId: params.accountId,
+    accountUserId: params.accountUserId,
+    accountOwnerUserId: params.accountOwnerUserId,
+    conversationId: params.chat.id,
+    api: params.api,
+    store: params.store,
+    memoryRoot: params.memoryRoot,
+    log: params.log,
+  });
+}
+
+export async function refreshAgentBehaviorProfile(params: {
+  platform: string;
+  accountId: string;
+  accountUserId: string;
+  accountOwnerUserId: string;
+  agentId?: string;
+  metadataVersion?: number;
+  api: ProfileSyncApi;
+  store: ProfileSyncStore;
+  memoryRoot?: string;
+  log?: { error?: (message: string) => void };
+}): Promise<void> {
+  if (!requireMemoryRoot(params.memoryRoot, params.log, "owner")) return;
+  try {
+    await pullOwnerMetadata({
+      memoryRoot: params.memoryRoot,
+      agentId: params.agentId ?? "",
+      accountUserId: params.accountUserId,
+      accountOwnerUserId: params.accountOwnerUserId,
+      api: params.api,
+    });
+  } catch (err) {
+    params.log?.error?.(
+      `clawchat-plugin-openclaw owner metadata refresh failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
+
+export async function syncFirstSeenClawChatProfiles(params: {
+  platform: string;
+  accountId: string;
+  accountUserId: string;
+  accountOwnerUserId: string;
+  chat: { id: string; type: "direct" | "group"; lastSeenAt?: number | null };
+  sender: { id: string; nickname?: string | null };
+  api: ProfileSyncApi;
+  store: ProfileSyncStore;
+  memoryRoot?: string;
+  log?: { error?: (message: string) => void };
+}): Promise<void> {
+  const { platform, accountId, accountUserId, accountOwnerUserId, chat, sender, api, store } = params;
+  await ensureGroupProfileForChat({
+    platform,
+    accountId,
+    chat,
+    accountUserId,
+    accountOwnerUserId,
+    api,
+    store,
+    memoryRoot: params.memoryRoot,
+    log: params.log,
+  });
+  await ensureUserProfileForSender({
+    platform,
+    accountId,
+    accountUserId,
+    accountOwnerUserId,
+    sender,
+    lastSeenAt: chat.lastSeenAt ?? null,
+    api,
+    store,
+    memoryRoot: params.memoryRoot,
+    log: params.log,
+  });
+
+}

package/src/prompt-injection.test.ts

@@ -0,0 +1,39 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  clearClawChatPromptInjections,
+  clearClawChatPromptInjectionForSession,
+  registerClawChatPromptInjection,
+  renderClawChatPromptInjectionForSession,
+  stageClawChatPromptInjection,
+} from "./prompt-injection.ts";
+
+const DIRECT_PROMPT = "\n[message]\n\nsender_is_agent_owner:";
+
+describe("ClawChat prompt injection", () => {
+  beforeEach(() => clearClawChatPromptInjections());
+
+  it("renders a staged user prompt by session key", () => {
+    stageClawChatPromptInjection({ sessionKey: "session-1", prompt: DIRECT_PROMPT });
+    expect(renderClawChatPromptInjectionForSession("session-1")).toBe(DIRECT_PROMPT);
+  });
+
+  it("clears a staged prompt by session key", () => {
+    stageClawChatPromptInjection({ sessionKey: "session-1", prompt: DIRECT_PROMPT });
+    clearClawChatPromptInjectionForSession("session-1");
+    expect(renderClawChatPromptInjectionForSession("session-1")).toBeUndefined();
+  });
+
+  it("consumes staged prompt through before_prompt_build appendSystemContext", async () => {
+    const handlers = new Map<string, Function>();
+    const api = {
+      on: vi.fn((name: string, handler: Function) => handlers.set(name, handler)),
+      logger: { info: vi.fn(), error: vi.fn() },
+    };
+    registerClawChatPromptInjection(api as never);
+    expect(api.on).toHaveBeenCalledWith("before_prompt_build", expect.any(Function), { priority: 100 });
+    stageClawChatPromptInjection({ sessionKey: "session-1", prompt: DIRECT_PROMPT });
+    const result = await handlers.get("before_prompt_build")?.({}, { sessionKey: "session-1" });
+    expect(result).toEqual({ appendSystemContext: DIRECT_PROMPT });
+    expect(renderClawChatPromptInjectionForSession("session-1")).toBeUndefined();
+  });
+});

package/src/prompt-injection.ts

@@ -0,0 +1,45 @@
+export type ClawChatPromptInjectionApi = {
+  on: (
+    name: "before_prompt_build",
+    handler: (
+      event: unknown,
+      ctx: { sessionKey?: string },
+    ) => Promise<{ appendSystemContext: string } | undefined>,
+    options?: { priority?: number },
+  ) => void;
+};
+
+const promptInjectionsBySessionKey = new Map<string, string>();
+
+export function clearClawChatPromptInjections(): void {
+  promptInjectionsBySessionKey.clear();
+}
+
+export function clearClawChatPromptInjectionForSession(sessionKey: string): void {
+  promptInjectionsBySessionKey.delete(sessionKey);
+}
+
+export function stageClawChatPromptInjection(params: { sessionKey: string; prompt: string }): void {
+  promptInjectionsBySessionKey.set(params.sessionKey, params.prompt);
+}
+
+export function renderClawChatPromptInjectionForSession(sessionKey: string): string | undefined {
+  return promptInjectionsBySessionKey.get(sessionKey);
+}
+
+export function registerClawChatPromptInjection(api: ClawChatPromptInjectionApi): void {
+  api.on(
+    "before_prompt_build",
+    async (_event, ctx) => {
+      const sessionKey = ctx.sessionKey;
+      if (!sessionKey) return undefined;
+
+      const prompt = promptInjectionsBySessionKey.get(sessionKey);
+      if (!prompt) return undefined;
+
+      promptInjectionsBySessionKey.delete(sessionKey);
+      return { appendSystemContext: prompt };
+    },
+    { priority: 100 },
+  );
+}

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 complete materialized messages as agent-dispatch events", () => {
+    expect(isBusinessDispatchEvent(EVENT.MESSAGE_SEND)).toBe(true);
+    expect(isBusinessDispatchEvent(EVENT.MESSAGE_REPLY)).toBe(true);
+    expect(isBusinessDispatchEvent(EVENT.MESSAGE_DONE)).toBe(false);
+    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;
+}