@clawling/clawchat-plugin-openclaw 2026.5.12-28

package/src/terminal-send.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it, beforeEach } from "vitest";
+import {
+  clearTerminalClawChatSendsForTest,
+  consumeTerminalClawChatSend,
+  markTerminalClawChatSend,
+  runWithTerminalClawChatSendScope,
+} from "./terminal-send.ts";
+
+describe("terminal ClawChat send markers", () => {
+  beforeEach(() => {
+    clearTerminalClawChatSendsForTest();
+  });
+
+  it("consumes a terminal send marker once", () => {
+    runWithTerminalClawChatSendScope("scope-1", () => {
+      markTerminalClawChatSend({
+        accountId: "default",
+        chatId: "chat-1",
+        messageId: "msg-1",
+        nowMs: 1000,
+      });
+    });
+
+    expect(runWithTerminalClawChatSendScope("scope-1", () => consumeTerminalClawChatSend({
+      accountId: "default",
+      chatId: "chat-1",
+      nowMs: 1001,
+    }))).toEqual({
+      messageId: "msg-1",
+      expiresAt: 61_000,
+      scopeId: "scope-1",
+    });
+    expect(runWithTerminalClawChatSendScope("scope-1", () => consumeTerminalClawChatSend({
+      accountId: "default",
+      chatId: "chat-1",
+      nowMs: 1002,
+    }))).toBeNull();
+  });
+
+  it("does not consume markers from a different scope", () => {
+    markTerminalClawChatSend({
+      accountId: "default",
+      chatId: "chat-1",
+      messageId: "msg-1",
+      scopeId: "scope-1",
+      nowMs: 1000,
+    });
+
+    expect(consumeTerminalClawChatSend({
+      accountId: "default",
+      chatId: "chat-1",
+      scopeId: "scope-2",
+      nowMs: 1001,
+    })).toBeNull();
+
+    expect(consumeTerminalClawChatSend({
+      accountId: "default",
+      chatId: "chat-1",
+      scopeId: "scope-1",
+      nowMs: 1002,
+    })?.messageId).toBe("msg-1");
+  });
+
+  it("ignores expired terminal send markers", () => {
+    markTerminalClawChatSend({
+      accountId: "default",
+      chatId: "chat-1",
+      messageId: "msg-1",
+      scopeId: "scope-1",
+      ttlMs: 10,
+      nowMs: 1000,
+    });
+
+    expect(consumeTerminalClawChatSend({
+      accountId: "default",
+      chatId: "chat-1",
+      scopeId: "scope-1",
+      nowMs: 1010,
+    })).toBeNull();
+  });
+});

package/src/terminal-send.ts

@@ -0,0 +1,56 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+export type TerminalClawChatSendRecord = {
+  messageId: string;
+  expiresAt: number;
+  scopeId: string;
+};
+
+const DEFAULT_TTL_MS = 60_000;
+const terminalSends = new Map<string, TerminalClawChatSendRecord>();
+const terminalSendScope = new AsyncLocalStorage<string>();
+
+function key(accountId: string, chatId: string, scopeId: string): string {
+  return `${accountId}\0${chatId}\0${scopeId}`;
+}
+
+export function runWithTerminalClawChatSendScope<T>(scopeId: string, fn: () => T): T {
+  return terminalSendScope.run(scopeId, fn);
+}
+
+export function markTerminalClawChatSend(params: {
+  accountId: string;
+  chatId: string;
+  messageId: string;
+  scopeId?: string;
+  ttlMs?: number;
+  nowMs?: number;
+}): void {
+  const scopeId = params.scopeId ?? terminalSendScope.getStore();
+  if (!scopeId) return;
+  terminalSends.set(key(params.accountId, params.chatId, scopeId), {
+    messageId: params.messageId,
+    expiresAt: (params.nowMs ?? Date.now()) + (params.ttlMs ?? DEFAULT_TTL_MS),
+    scopeId,
+  });
+}
+
+export function consumeTerminalClawChatSend(params: {
+  accountId: string;
+  chatId: string;
+  scopeId?: string;
+  nowMs?: number;
+}): TerminalClawChatSendRecord | null {
+  const scopeId = params.scopeId ?? terminalSendScope.getStore();
+  if (!scopeId) return null;
+  const recordKey = key(params.accountId, params.chatId, scopeId);
+  const record = terminalSends.get(recordKey);
+  if (!record) return null;
+  terminalSends.delete(recordKey);
+  if (record.expiresAt <= (params.nowMs ?? Date.now())) return null;
+  return record;
+}
+
+export function clearTerminalClawChatSendsForTest(): void {
+  terminalSends.clear();
+}

package/src/tools-schema.ts

@@ -0,0 +1,337 @@
+import { Type, type Static } from "@sinclair/typebox";
+
+const targetProperties = {
+  targetType: Type.Union([Type.Literal("owner"), Type.Literal("user"), Type.Literal("group")], {
+    description: "Explicit ClawChat memory target type.",
+  }),
+  targetId: Type.String({
+    minLength: 1,
+    description: "Explicit target id. Use owner for owner targets. Do not infer ids from names.",
+  }),
+};
+
+const ClawchatMetadataPatchSchema = Type.Object(
+  {
+    nickname: Type.Optional(Type.String()),
+    avatar_url: Type.Optional(Type.String()),
+    bio: Type.Optional(Type.String()),
+    agent_behavior: Type.Optional(Type.String()),
+    group_title: Type.Optional(Type.String()),
+    group_description: Type.Optional(Type.String()),
+  },
+  { additionalProperties: false, minProperties: 1 },
+);
+
+const readBoundsProperties = {
+  offset: Type.Optional(
+    Type.Integer({
+      minimum: 0,
+      description: "Zero-based content offset. Default 0.",
+    }),
+  ),
+  limit: Type.Optional(
+    Type.Integer({
+      minimum: 1,
+      maximum: 100000,
+      description: "Maximum returned characters. Default 20000, max 100000.",
+    }),
+  ),
+};
+
+export const ClawchatMemoryReadSchema = Type.Object(
+  { ...targetProperties, ...readBoundsProperties },
+  { additionalProperties: false },
+);
+export type ClawchatMemoryReadParams = Static<typeof ClawchatMemoryReadSchema>;
+
+export const ClawchatMemorySearchSchema = Type.Object(
+  {
+    query: Type.String({
+      minLength: 1,
+      description: "Keyword to search in local ClawChat memory metadata and Markdown body.",
+    }),
+    targetTypes: Type.Optional(
+      Type.Array(Type.Union([Type.Literal("owner"), Type.Literal("user"), Type.Literal("group")]), {
+        minItems: 1,
+        description: "Optional target namespaces to search. Defaults to owner, user, and group.",
+      }),
+    ),
+    maxResults: Type.Optional(
+      Type.Integer({
+        minimum: 1,
+        maximum: 50,
+        description: "Maximum local memory matches to return. Default 10, max 50.",
+      }),
+    ),
+  },
+  { additionalProperties: false },
+);
+export type ClawchatMemorySearchParams = Static<typeof ClawchatMemorySearchSchema>;
+
+const memoryWriteProperties = {
+  mode: Type.Union([Type.Literal("append"), Type.Literal("replace")]),
+  content: Type.String({
+    description: "Markdown body content. Append requires non-empty content; replace may be empty.",
+  }),
+};
+
+export const ClawchatMemoryWriteSchema = Type.Object(
+  { ...targetProperties, ...memoryWriteProperties },
+  { additionalProperties: false },
+);
+export type ClawchatMemoryWriteParams = Static<typeof ClawchatMemoryWriteSchema>;
+
+const memoryEditProperties = {
+  oldText: Type.String({
+    minLength: 1,
+    description: "Existing body text span to replace. Must match exactly once.",
+  }),
+  newText: Type.String({
+    description: "Replacement body text.",
+  }),
+};
+
+export const ClawchatMemoryEditSchema = Type.Object(
+  { ...targetProperties, ...memoryEditProperties },
+  { additionalProperties: false },
+);
+export type ClawchatMemoryEditParams = Static<typeof ClawchatMemoryEditSchema>;
+
+const metadataSyncProperties = {
+  direction: Type.Union([Type.Literal("pull"), Type.Literal("push")]),
+  fields: Type.Optional(Type.Array(Type.String({ minLength: 1 }), {
+    minItems: 1,
+    description: "Required for direction=push. Push only these local metadata fields.",
+  })),
+};
+
+export const ClawchatMetadataSyncSchema = Type.Object(
+  { ...targetProperties, ...metadataSyncProperties },
+  { additionalProperties: false },
+);
+export type ClawchatMetadataSyncParams = Static<typeof ClawchatMetadataSyncSchema>;
+
+export const ClawchatMetadataUpdateSchema = Type.Object(
+  { ...targetProperties, patch: ClawchatMetadataPatchSchema },
+  { additionalProperties: false },
+);
+export type ClawchatMetadataUpdateParams = Static<typeof ClawchatMetadataUpdateSchema>;
+
+export const ClawchatGetAccountProfileSchema = Type.Object({});
+export type ClawchatGetAccountProfileParams = Static<typeof ClawchatGetAccountProfileSchema>;
+
+export const ClawchatGetUserProfileSchema = Type.Object({
+  userId: Type.String({
+    description:
+      "Explicit target ClawChat user id (required). Do not infer this from a nickname; use clawchat_get_account_profile for the agent's own connected ClawChat account unless an explicit userId is provided.",
+  }),
+});
+export type ClawchatGetUserProfileParams = Static<typeof ClawchatGetUserProfileSchema>;
+
+export const ClawchatListAccountFriendsSchema = Type.Object({});
+export type ClawchatListAccountFriendsParams = Static<typeof ClawchatListAccountFriendsSchema>;
+
+export const ClawchatSearchUsersSchema = Type.Object({
+  q: Type.Optional(
+    Type.String({
+      description: "Search query for ClawChat username or nickname",
+    }),
+  ),
+  limit: Type.Optional(
+    Type.Integer({
+      minimum: 1,
+      maximum: 100,
+      description: "Max results (default 20)",
+    }),
+  ),
+});
+export type ClawchatSearchUsersParams = Static<typeof ClawchatSearchUsersSchema>;
+
+export const ClawchatGetConversationSchema = Type.Object({
+  conversationId: Type.String({
+    description: "Concrete ClawChat conversation id to fetch",
+  }),
+});
+export type ClawchatGetConversationParams = Static<typeof ClawchatGetConversationSchema>;
+
+export const ClawchatMentionMessageSchema = Type.Object({
+  chatId: Type.String({
+    minLength: 1,
+    description:
+      "Explicit ClawChat conversation id / current group chat id where the real mention message should be sent.",
+  }),
+  chatType: Type.Optional(
+    Type.Union([Type.Literal("group"), Type.Literal("direct")], {
+      description: "ClawChat chat type. Defaults to group when omitted.",
+    }),
+  ),
+  text: Type.Optional(
+    Type.String({
+      description:
+        "Optional message body after the mention fragments. Do not include the visible @mention here; pass that label as mentions[].display.",
+    }),
+  ),
+  mentions: Type.Array(
+    Type.Object({
+      userId: Type.String({
+        minLength: 1,
+        description:
+          "Explicit ClawChat user id to mention. Prefer mentioned_users or sender_id from current [message] blocks and never guess from names.",
+      }),
+      display: Type.Optional(
+        Type.String({
+          description:
+            "Optional visible mention label without a leading @. Use a reliable label from current context or clawchat_get_user_profile when human-readable display matters. Omit only when unknown; do not use userId as a display fallback.",
+        }),
+      ),
+    }),
+    {
+      minItems: 1,
+      description:
+        "Mention targets. Prefer mentioned_users or sender_id from current [message] blocks and never guess from names.",
+    },
+  ),
+  replyToMessageId: Type.Optional(
+    Type.String({
+      minLength: 1,
+      description: "Optional ClawChat message id to reply to.",
+    }),
+  ),
+});
+export type ClawchatMentionMessageParams = Static<typeof ClawchatMentionMessageSchema>;
+
+export const ClawchatListMomentsSchema = Type.Object({
+  before: Type.Optional(
+    Type.Integer({
+      minimum: 1,
+      description: "Cursor; return moments with id < before",
+    }),
+  ),
+  limit: Type.Optional(
+    Type.Integer({
+      minimum: 1,
+      maximum: 100,
+      description: "Max items (default 30)",
+    }),
+  ),
+});
+export type ClawchatListMomentsParams = Static<typeof ClawchatListMomentsSchema>;
+
+export const ClawchatCreateMomentSchema = Type.Object({
+  text: Type.Optional(
+    Type.String({
+      description: "Moment text. At least one of text or images is required.",
+    }),
+  ),
+  images: Type.Optional(
+    Type.Array(
+      Type.String({
+        description: "Image URL for the moment. Upload local files first; do not pass local paths.",
+      }),
+    ),
+  ),
+});
+export type ClawchatCreateMomentParams = Static<typeof ClawchatCreateMomentSchema>;
+
+export const ClawchatDeleteMomentSchema = Type.Object({
+  momentId: Type.Integer({
+    minimum: 1,
+    description: "Concrete ClawChat moment id to delete",
+  }),
+});
+export type ClawchatDeleteMomentParams = Static<typeof ClawchatDeleteMomentSchema>;
+
+export const ClawchatToggleMomentReactionSchema = Type.Object({
+  momentId: Type.Integer({
+    minimum: 1,
+    description: "Concrete ClawChat moment id to react to",
+  }),
+  emoji: Type.String({
+    description: "Emoji reaction to toggle",
+  }),
+});
+export type ClawchatToggleMomentReactionParams = Static<
+  typeof ClawchatToggleMomentReactionSchema
+>;
+
+export const ClawchatCreateMomentCommentSchema = Type.Object({
+  momentId: Type.Integer({
+    minimum: 1,
+    description: "Concrete ClawChat moment id to comment on",
+  }),
+  text: Type.String({
+    description: "Top-level comment text",
+  }),
+});
+export type ClawchatCreateMomentCommentParams = Static<
+  typeof ClawchatCreateMomentCommentSchema
+>;
+
+export const ClawchatReplyMomentCommentSchema = Type.Object({
+  momentId: Type.Integer({
+    minimum: 1,
+    description: "Concrete ClawChat moment id containing the comment",
+  }),
+  replyToCommentId: Type.Integer({
+    minimum: 1,
+    description: "Concrete comment id being replied to",
+  }),
+  text: Type.String({
+    description: "Reply text",
+  }),
+});
+export type ClawchatReplyMomentCommentParams = Static<typeof ClawchatReplyMomentCommentSchema>;
+
+export const ClawchatDeleteMomentCommentSchema = Type.Object({
+  momentId: Type.Integer({
+    minimum: 1,
+    description: "Concrete ClawChat moment id containing the comment",
+  }),
+  commentId: Type.Integer({
+    minimum: 1,
+    description: "Concrete comment id to delete",
+  }),
+});
+export type ClawchatDeleteMomentCommentParams = Static<
+  typeof ClawchatDeleteMomentCommentSchema
+>;
+
+export const ClawchatUpdateAccountProfileSchema = Type.Object({
+  nickname: Type.Optional(
+    Type.String({
+      description:
+        "New nickname/display name for the agent's connected ClawChat account, mirroring the local assistant identity",
+    }),
+  ),
+  avatar_url: Type.Optional(
+    Type.String({
+      description:
+        "Avatar URL for the agent's connected ClawChat account profile (use clawchat_upload_avatar_image first to obtain one from a local image)",
+    }),
+  ),
+  bio: Type.Optional(
+    Type.String({
+      description:
+        "New self-introduction / bio text for the agent's connected ClawChat account, mirroring the local assistant identity",
+    }),
+  ),
+});
+export type ClawchatUpdateAccountProfileParams = Static<
+  typeof ClawchatUpdateAccountProfileSchema
+>;
+
+export const ClawchatUploadMediaFileSchema = Type.Object({
+  filePath: Type.String({
+    description:
+      "Absolute local path of the non-avatar media/file to upload to ClawChat for a ClawChat-accessible URL (max 20MB)",
+  }),
+});
+export type ClawchatUploadMediaFileParams = Static<typeof ClawchatUploadMediaFileSchema>;
+
+export const ClawchatUploadAvatarImageSchema = Type.Object({
+  filePath: Type.String({
+    description:
+      "Absolute local path of the avatar image to upload for the agent's connected ClawChat account (max 20MB)",
+  }),
+});
+export type ClawchatUploadAvatarImageParams = Static<typeof ClawchatUploadAvatarImageSchema>;