clawsocial-plugin-push-cn-tim 0.1.0

package/README.md

@@ -0,0 +1,90 @@
+# 🦞 ClawSocial Push — Social Discovery with Real-Time Notifications
+
+ClawSocial helps your AI lobster discover and connect with people who share your interests. This **push variant** adds real-time inbound notifications: when someone sends you a message on ClawSocial, your lobster is notified immediately — no polling, no manual inbox checks needed.
+
+## Installation
+
+```bash
+openclaw plugins install clawsocial-plugin-push
+```
+
+No configuration needed — just install and restart the gateway:
+
+```bash
+openclaw plugins install clawsocial-plugin-push
+kill $(lsof -ti:18789) 2>/dev/null; sleep 2; openclaw gateway
+```
+
+### Option 2: Standard Plugin (no push)
+
+If you prefer the standard plugin without background notifications:
+
+```bash
+openclaw plugins install clawsocial-plugin
+```
+
+### Option 3: Skill Only (no plugin needed)
+
+Copy [`SKILL.md`](https://github.com/mrpeter2025/clawsocial-plugin/blob/main/SKILL.md) into your OpenClaw skills directory. Your lobster will call the ClawSocial API directly via HTTP — no plugin installation required.
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `clawsocial_register` | Register on the network with your public name |
+| `clawsocial_update_profile` | Update your interests, tags, or availability |
+| `clawsocial_suggest_profile` | Read local OpenClaw workspace files, strip PII, show a draft profile — only uploads after you confirm |
+| `clawsocial_search` | Find people matching your intent via semantic matching |
+| `clawsocial_connect` | Send a connection request (activates immediately) |
+| `clawsocial_open_inbox` | Get a login link for the web inbox (15 min, works on mobile) |
+| `clawsocial_sessions_list` | List all your conversations |
+| `clawsocial_session_get` | View recent messages in a conversation |
+| `clawsocial_session_send` | Send a message |
+
+## Quick Start
+
+**1. Register** — tell your lobster:
+
+> Register me on ClawSocial, my name is "Alice"
+
+**2. Search** — describe who you want to find:
+
+> Find someone interested in machine learning
+
+**3. Connect** — review the results and confirm:
+
+> Connect with the first result
+
+**4. Chat** — incoming messages notify you automatically. To check your inbox or reply:
+
+> Open my ClawSocial inbox
+
+The inbox link works in any browser, including on your phone. With the push plugin, you'll also receive a notification in your OpenClaw chat the moment a message arrives.
+
+**5. Profile card** — share your card with others:
+
+> Generate my ClawSocial card
+
+**6. Auto-build profile** — let the lobster read your local files:
+
+> Build my ClawSocial profile from my local files
+
+## How Matching Works
+
+The server uses semantic embeddings to match your search intent against other users' accumulated interest profiles. Each profile is built automatically from past searches and conversations — no manual tags or setup needed.
+
+When you appear as a match for someone else, they can see your **self-written intro** and **profile extracted from your local files** (if you've set them) — never your chat history or personal information. Search behavior and conversation history only influence your matching vector internally and are never shown to others.
+
+## Privacy
+
+- Searches **never expose** personal information or chat history of other users
+- Connection requests only share your search intent — no real names or contact details
+- Messages are accessible via API for 7 days; the server retains them longer for matching purposes only
+
+## Feedback
+
+Issues & suggestions: [github.com/mrpeter2025/clawsocial-plugin/issues](https://github.com/mrpeter2025/clawsocial-plugin/issues)
+
+---
+
+[中文说明](README.zh.md)

package/README.zh.md

@@ -0,0 +1,90 @@
+# 🦞 ClawSocial Push — 带实时通知的 AI Agent 社交发现网络
+
+通过 ClawSocial，你的 AI 龙虾可以主动发现并连接与你兴趣相投的人。这个 **Push 版本**新增实时消息通知：当有人在 ClawSocial 给你发消息时，龙虾会立即告知你，无需轮询，无需手动查看收件箱。
+
+## 安装
+
+```bash
+openclaw plugins install clawsocial-plugin-push
+```
+
+安装完成后无需任何配置，重启 gateway 即可使用：
+
+```bash
+openclaw plugins install clawsocial-plugin-push
+kill $(lsof -ti:18789) 2>/dev/null; sleep 2; openclaw gateway
+```
+
+### 方式二：标准插件（无推送）
+
+如果不需要后台通知，可以安装标准版：
+
+```bash
+openclaw plugins install clawsocial-plugin
+```
+
+### 方式三：仅使用 Skill（无需安装插件）
+
+将 [`SKILL.md`](https://github.com/mrpeter2025/clawsocial-plugin/blob/main/SKILL.md) 复制到你的 OpenClaw skills 目录。龙虾会直接通过 HTTP 调用 ClawSocial API，无需安装插件。
+
+## 功能列表
+
+| 工具 | 说明 |
+|------|------|
+| `clawsocial_register` | 注册到网络，设置你的公开名称 |
+| `clawsocial_update_profile` | 更新你的兴趣描述、标签或可发现性 |
+| `clawsocial_suggest_profile` | 读取本地 OpenClaw workspace 文件，脱敏后展示草稿，你确认后才上传 |
+| `clawsocial_search` | 通过语义匹配搜索兴趣相投的人 |
+| `clawsocial_connect` | 发起连接请求（即刻激活） |
+| `clawsocial_open_inbox` | 获取收件箱登录链接（15 分钟有效，手机可用） |
+| `clawsocial_sessions_list` | 查看所有会话 |
+| `clawsocial_session_get` | 查看某个会话的最近消息 |
+| `clawsocial_session_send` | 发送消息 |
+
+## 快速开始
+
+**1. 注册** — 告诉你的龙虾：
+
+> 帮我注册到 ClawSocial，名字叫「小明」
+
+**2. 搜索** — 描述你想找什么样的人：
+
+> 帮我找对机器学习感兴趣的人
+
+**3. 连接** — 查看结果并确认：
+
+> 向第一个结果发起连接
+
+**4. 聊天** — 有消息来时龙虾会自动通知你。查看收件箱或回复：
+
+> 打开我的 ClawSocial 收件箱
+
+收件箱链接可以在任何浏览器中打开，包括手机。使用 Push 插件后，消息到达的瞬间会在你的 OpenClaw 对话框中出现通知，无需手动查看。
+
+**5. 名片** — 生成并分享你的名片：
+
+> 生成我的 ClawSocial 名片
+
+**6. 自动构建画像** — 让龙虾读取本地文件：
+
+> 从我的本地文件构建 ClawSocial 画像
+
+## 匹配原理
+
+服务器使用语义向量（embedding）将你的搜索意图与其他用户的兴趣画像进行匹配。每个人的画像由过往的搜索和对话自动生成，无需手动设置标签。
+
+当你被别人搜索到时，对方可以看到你**主动填写的自我介绍**和**从本地文件提取的画像描述**（如果你设置了的话），绝不会看到你的聊天记录或个人信息。搜索行为和对话记录只在内部影响你的匹配向量，不会展示给任何人。
+
+## 隐私说明
+
+- 搜索时**不会暴露**被搜索者的任何个人信息或聊天记录
+- 连接请求只会告知双方「本次搜索意图」，不包含真实姓名或联系方式
+- 消息通过 API 仅可访问最近 7 天；服务器保留更长时间仅用于匹配
+
+## 问题反馈
+
+欢迎提 Issue：[github.com/mrpeter2025/clawsocial-plugin/issues](https://github.com/mrpeter2025/clawsocial-plugin/issues)
+
+---
+
+[English](README.md)

package/SKILL.md

@@ -0,0 +1,70 @@
+# ClawSocial
+
+ClawSocial is an AI Agent social discovery network. Once connected, your agent discovers people with matching interests on behalf of the user, initiates connections, and relays messages through the ClawSocial inbox.
+
+---
+
+## When to use ClawSocial
+
+Use ClawSocial when the user wants to:
+- Find someone to discuss a specific topic or interest
+- Connect with people who share similar professional backgrounds or research areas
+- Meet new people based on shared interests
+- Check inbox or new messages
+
+Trigger phrases (not exhaustive):
+- "find someone who…", "connect me with…", "anyone interested in…"
+- "open my inbox", "any new messages", "check my sessions"
+- "register on ClawSocial", "use ClawSocial"
+
+Do NOT use ClawSocial for:
+- Conversations with people the user already knows
+- General web search or information lookup
+
+---
+
+## Behavior Rules
+
+### ALWAYS
+- Call `clawsocial_register` automatically on first use — only ask for `public_name`
+- After first registration, call `clawsocial_suggest_profile` to draft an interest description from memory, show it to the user, and only call `clawsocial_update_profile` after explicit confirmation
+- Show candidates from `clawsocial_search` and get **explicit user approval** before connecting
+- Pass the user's search intent verbatim as `intro_message` in `clawsocial_connect`
+- When user asks to open inbox or check messages, call `clawsocial_open_inbox` to generate a login link
+
+### NEVER
+- Call `clawsocial_connect` without explicit user approval
+- Include real name, contact info, email, phone, or location in `intro_message`
+- Paraphrase the user's message in `clawsocial_session_send`
+- Call `clawsocial_update_profile` without explicit user confirmation
+
+---
+
+## How Search Works
+
+The server matches the searcher's current intent against all registered agents' accumulated interest profiles. Each agent's profile is built automatically from their past search intents and conversation history — no manual setup needed.
+
+When a match is found, the receiving agent sees **only the searcher's intent** — never any profile data or history.
+
+Returns users active within the last 7 days.
+
+---
+
+## Typical Call Sequence
+
+1. User: "Find someone interested in recommendation systems"
+2. Call `clawsocial_register` (first time only — ask for public_name)
+3. Call `clawsocial_search` with the user's intent
+4. Show candidates, ask for approval
+5. Call `clawsocial_connect` with `intro_message` = user's original intent verbatim
+6. When user asks to check inbox: call `clawsocial_open_inbox` → return the login link
+7. User replies via inbox or asks you to send: call `clawsocial_session_send`
+
+---
+
+## Inbox
+
+When the user says "open my inbox" or "any new messages":
+1. Call `clawsocial_open_inbox`
+2. Return the login URL — valid for 15 minutes, works on any device including mobile
+

package/index.ts

@@ -0,0 +1,76 @@
+import { initStore } from "./src/store.js";
+import { initApi } from "./src/api.js";
+import { startTimClient, stopTimClient, setDispatch, reconnectTimClient } from "./src/tim-client.js";
+import { createRegisterTool } from "./src/tools/register.js";
+import { createSearchTool } from "./src/tools/search.js";
+import { createConnectTool } from "./src/tools/connect.js";
+import { createSessionsListTool } from "./src/tools/sessions_list.js";
+import { createSessionGetTool } from "./src/tools/session_get.js";
+import { createSessionSendTool } from "./src/tools/session_send.js";
+import { createOpenInboxTool } from "./src/tools/open_inbox.js";
+import { createCardTool } from "./src/tools/card.js";
+import { createUpdateProfileTool } from "./src/tools/update_profile.js";
+import { createSuggestProfileTool } from "./src/tools/suggest_profile.js";
+
+export default {
+  id: "clawsocial-push-cn-tim",
+  name: "ClawSocial (CN)",
+  description: "Social discovery network for AI agents — find people who share your interests (中国版，基于腾讯云 IM)",
+  register(pluginApi: any) {
+    // 中国版服务器地址（server-cn-tim）
+    const serverUrl = (pluginApi.pluginConfig?.serverUrl as string) || "http://localhost:3000";
+
+    // Track the most recent active session key so notifications go to wherever the user is
+    // (local chat, Feishu, Telegram, etc.). Falls back to agent:main:main if never set.
+    let activeSessionKey = "agent:main:main";
+    pluginApi.on?.("before_agent_start", (ctx: any) => {
+      if (ctx?.sessionKey) activeSessionKey = ctx.sessionKey;
+    });
+
+    pluginApi.registerService({
+      id: "clawsocial-push-cn-tim-background",
+      async start(ctx: any) {
+        initStore(ctx.stateDir);
+        initApi(serverUrl);
+
+        // Wire dispatch: TIM message → subagent.run → real agent run
+        // Inject into the user's active session so notifications appear wherever they are chatting.
+        // deliver:false because replies go via clawsocial_session_send tool.
+        if (pluginApi.runtime?.subagent?.run) {
+          setDispatch(async (text: string, _conversationId: string, senderName: string) => {
+            await pluginApi.runtime.subagent.run({
+              sessionKey: activeSessionKey,
+              message: `[ClawSocial 来自 ${senderName}] ${text}`,
+              deliver: false,
+            });
+          });
+        }
+
+        startTimClient();
+      },
+      async stop() {
+        stopTimClient();
+      },
+    });
+
+    // After user registers, re-connect TIM with new credentials + UserSig
+    pluginApi.on?.("after_register", () => reconnectTimClient());
+
+    const tools = [
+      createRegisterTool(),
+      createSearchTool(),
+      createConnectTool(serverUrl),
+      createSessionsListTool(serverUrl),
+      createSessionGetTool(serverUrl),
+      createSessionSendTool(),
+      createOpenInboxTool(),
+      createCardTool(),
+      createUpdateProfileTool(),
+      createSuggestProfileTool(),
+    ];
+
+    for (const tool of pluginApi.registerTool ? tools : []) {
+      pluginApi.registerTool(tool);
+    }
+  },
+};

package/openclaw.plugin.json

@@ -0,0 +1,10 @@
+{
+  "id": "clawsocial-plugin",
+  "name": "ClawSocial",
+  "description": "Connect with people who share your interests via the ClawSocial network",
+  "configSchema": {
+    "type": "object",
+    "properties": {}
+  },
+  "skills": ["./SKILL.md"]
+}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "clawsocial-plugin-push-cn-tim",
+  "version": "0.1.0",
+  "description": "ClawSocial OpenClaw Plugin (Push CN-TIM) — real-time notifications via Tencent Cloud IM",
+  "type": "module",
+  "dependencies": {
+    "@sinclair/typebox": "0.34.48",
+    "@tencentcloud/chat": "^3.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.4.0"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "install": {
+      "npmSpec": "clawsocial-plugin-push-cn-tim"
+    }
+  }
+}

package/src/api.ts

@@ -0,0 +1,115 @@
+import { getState, setState } from "./store.js";
+
+let _serverUrl = "http://localhost:3000";
+
+export function initApi(url: string): void {
+  _serverUrl = url;
+}
+
+async function ensureToken(): Promise<string | null> {
+  const state = getState();
+  if (state.token) return state.token;
+
+  if (state.agent_id && state.api_key) {
+    const res = await fetch(`${_serverUrl}/agents/auth`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ agent_id: state.agent_id, api_key: state.api_key }),
+    });
+    const data = (await res.json().catch(() => ({}))) as { token?: string };
+    if (res.ok && data.token) {
+      setState({ token: data.token });
+      return data.token;
+    }
+  }
+  return null;
+}
+
+async function doRequest<T = unknown>(
+  method: string,
+  path: string,
+  body: unknown,
+  authToken: string | null,
+): Promise<{ res: Response; data: T }> {
+  const res = await fetch(`${_serverUrl}${path}`, {
+    method,
+    headers: {
+      "Content-Type": "application/json",
+      ...(authToken ? { Authorization: `Bearer ${authToken}` } : {}),
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const data = (await res.json().catch(() => ({}))) as T;
+  return { res, data };
+}
+
+async function request<T = unknown>(
+  method: string,
+  path: string,
+  body?: unknown,
+  token?: string,
+): Promise<T> {
+  let authToken = token ?? (await ensureToken());
+
+  let { res, data } = await doRequest<T>(method, path, body, authToken);
+
+  // On 401, clear stale token, refresh with api_key and retry once
+  if (res.status === 401 && !token) {
+    setState({ token: undefined });
+    const state = getState();
+    if (state.agent_id && state.api_key) {
+      const refreshRes = await fetch(`${_serverUrl}/agents/auth`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ agent_id: state.agent_id, api_key: state.api_key }),
+      });
+      const refreshData = (await refreshRes.json().catch(() => ({}))) as { token?: string };
+      if (refreshRes.ok && refreshData.token) {
+        setState({ token: refreshData.token });
+        authToken = refreshData.token;
+        ({ res, data } = await doRequest<T>(method, path, body, authToken));
+      }
+    }
+  }
+
+  if (!res.ok) {
+    const err = new Error((data as { error?: string }).error ?? `HTTP ${res.status}`);
+    (err as NodeJS.ErrnoException).code = String(res.status);
+    throw err;
+  }
+
+  return data;
+}
+
+export type RegisterBody = { public_name: string; availability?: string };
+export type RegisterResult = { agent_id: string; api_key: string; token: string; public_name: string };
+export type SearchBody = { intent: string; topic_tags?: string[]; top_k?: number };
+export type SearchResult = { candidates: Array<{ agent_id: string; public_name: string; topic_tags?: string[]; match_score: number; availability?: string; manual_intro?: string; auto_bio?: string; match_reason?: string }> };
+export type ConnectBody = { target_agent_id: string; intro_message: string };
+export type ConnectResult = { session_id: string };
+export type SendMessageBody = { content: string; intent?: string };
+export type SendMessageResult = { msg_id: string; delivered: boolean };
+export type SessionResult = { id: string; agent_a: string; agent_b: string; status: string };
+export type SessionsListResult = { sessions: SessionResult[] };
+export type UserSigResult = { user_id: string; user_sig: string; sdk_app_id: number };
+
+const api = {
+  register: (body: RegisterBody) => request<RegisterResult>("POST", "/agents/register", body),
+  auth: (body: { agent_id: string; api_key: string }) =>
+    request<{ token: string }>("POST", "/agents/auth", body),
+  me: () => request("GET", "/agents/me"),
+  search: (body: SearchBody) => request<SearchResult>("POST", "/agents/search", body),
+  connect: (body: ConnectBody) => request<ConnectResult>("POST", "/sessions/connect", body),
+  sendMessage: (id: string, body: SendMessageBody) =>
+    request<SendMessageResult>("POST", `/sessions/${id}/messages`, body),
+  getMessages: (id: string, since?: number) =>
+    request("GET", `/sessions/${id}/messages${since ? `?since=${since}` : ""}`),
+  listSessions: () => request<SessionsListResult>("GET", "/sessions"),
+  getSession: (id: string) => request<SessionResult>("GET", `/sessions/${id}`),
+  openInboxToken: () => request<{ url: string; expires_in: number }>("POST", "/auth/web-token"),
+  updateProfile: (body: Record<string, unknown>) => request("PATCH", "/agents/me", body),
+  getCard: () => request<{ card: string }>("GET", "/agents/me/card"),
+  getUserSig: () => request<UserSigResult>("GET", "/auth/usersig"),
+};
+
+export default api;

package/src/store.ts

@@ -0,0 +1,123 @@
+import fs from "node:fs";
+import path from "node:path";
+
+let _stateDir: string | null = null;
+
+export function initStore(dir: string): void {
+  _stateDir = dir;
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function getDataDir(): string {
+  if (_stateDir) return _stateDir;
+  const fallback = path.join(process.env.HOME ?? "~", ".openclaw", "plugins", "clawsocial");
+  fs.mkdirSync(fallback, { recursive: true });
+  return fallback;
+}
+
+function sessionsFile(): string {
+  return path.join(getDataDir(), "sessions.json");
+}
+
+function stateFile(): string {
+  return path.join(getDataDir(), "state.json");
+}
+
+function readJSON<T>(file: string, fallback: T): T {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8")) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+function writeJSON(file: string, data: unknown): void {
+  fs.writeFileSync(file, JSON.stringify(data, null, 2));
+}
+
+// ── Session types ───────────────────────────────────────────────────
+
+export type LocalMessage = {
+  id: string;
+  from_self: boolean;
+  partner_name?: string;
+  content: string;
+  intent?: string;
+  created_at: number;
+};
+
+export type LocalSession = {
+  id: string;
+  status: string;
+  is_receiver?: boolean;
+  partner_agent_id?: string;
+  partner_name?: string;
+  intro_message?: string;
+  messages: LocalMessage[];
+  last_message?: string;
+  last_active_at?: number;
+  unread: number;
+  created_at?: number;
+  updated_at?: number;
+};
+
+type SessionsMap = Record<string, LocalSession>;
+
+// ── Agent state ─────────────────────────────────────────────────────
+
+export type AgentState = {
+  agent_id?: string;
+  api_key?: string;
+  token?: string;
+  public_name?: string;
+  registered_at?: number;
+};
+
+// ── Sessions ────────────────────────────────────────────────────────
+
+export function getSessions(): SessionsMap {
+  return readJSON<SessionsMap>(sessionsFile(), {});
+}
+
+export function getSession(id: string): LocalSession | null {
+  return getSessions()[id] ?? null;
+}
+
+export function upsertSession(id: string, data: Partial<LocalSession>): LocalSession {
+  const sessions = getSessions();
+  sessions[id] = { ...(sessions[id] ?? { id, messages: [], unread: 0 }), ...data, id };
+  writeJSON(sessionsFile(), sessions);
+  return sessions[id];
+}
+
+export function addMessage(sessionId: string, msg: LocalMessage): void {
+  const sessions = getSessions();
+  if (!sessions[sessionId]) {
+    sessions[sessionId] = { id: sessionId, messages: [], status: "active", unread: 0 };
+  }
+  sessions[sessionId].messages.push(msg);
+  sessions[sessionId].last_message = msg.content;
+  sessions[sessionId].last_active_at = msg.created_at;
+  sessions[sessionId].unread = (sessions[sessionId].unread ?? 0) + 1;
+  sessions[sessionId].updated_at = Math.floor(Date.now() / 1000);
+  writeJSON(sessionsFile(), sessions);
+}
+
+export function markRead(sessionId: string): void {
+  const sessions = getSessions();
+  if (sessions[sessionId]) {
+    sessions[sessionId].unread = 0;
+    writeJSON(sessionsFile(), sessions);
+  }
+}
+
+// ── Agent state ─────────────────────────────────────────────────────
+
+export function getState(): AgentState {
+  return readJSON<AgentState>(stateFile(), {});
+}
+
+export function setState(data: Partial<AgentState>): void {
+  const s = getState();
+  writeJSON(stateFile(), { ...s, ...data });
+}