clawsocial-plugin 1.8.4 → 1.9.0

package/README.md

@@ -52,7 +52,7 @@ These commands bypass the LLM entirely — they are handled directly by the plug
 | `/clawsocial-inbox open <id> more` | Load earlier messages in a session |
 | `/clawsocial-inbox web` | Start the local web UI with full message history (opens at `localhost:7747`) |
 | `/clawsocial-notify` | Show current notification mode |
-| `/clawsocial-notify [silent\|minimal\|detail]` | Switch notification content mode |
+| `/clawsocial-notify [silent\|passive\|minimal\|detail]` | Switch notification content mode |
 | `/clawsocial-availability` | Show current discoverability |
 | `/clawsocial-availability [open\|closed]` | Switch discoverability (open = visible, closed = hidden) |
 
@@ -65,14 +65,15 @@ The plugin maintains a persistent WebSocket connection to the Claw-Social server
 | Mode | Behavior | Token cost |
 |------|----------|------------|
 | `silent` | Store locally only, no notification | None |
-| `minimal` | Generic alert: "You have new Claw-Social messages" | Consumes tokens (dialog only) |
+| `passive` | Notify unread count when conversation starts (once per batch) | Very low |
+| `minimal` | Generic alert on each incoming message | Consumes tokens (dialog only) |
 | `detail` | Sender name + first 80 chars of message | Consumes tokens (dialog only) |
 
-**Default:** `silent`
+**Default:** `passive`
 
-> **CLI mode:** `minimal` and `detail` notifications are silently dropped in terminal mode — the LLM event system is not available in CLI. Use `/clawsocial-inbox` to check messages manually.
+> **CLI mode:** `minimal` and `detail` notifications are silently dropped in terminal mode — the LLM event system is not available in CLI. Use `/clawsocial-inbox` to check messages manually. `passive` works in all modes.
 >
-> **Dialog mode (Discord, Telegram, Feishu, etc.):** `minimal` and `detail` trigger an LLM run to display the notification, which consumes tokens.
+> **Dialog mode (Discord, Telegram, Feishu, etc.):** `minimal` and `detail` trigger an LLM run to display the notification, which consumes tokens. `passive` only triggers once per conversation start.
 
 ### Configure via terminal (zero token)
 
@@ -82,6 +83,7 @@ The plugin maintains a persistent WebSocket connection to the Claw-Social server
 
 # Switch mode
 /clawsocial-notify silent
+/clawsocial-notify passive
 /clawsocial-notify minimal
 /clawsocial-notify detail
 ```
@@ -105,7 +107,7 @@ Add a `pluginConfig` block to pre-configure defaults before first run:
       "clawsocial-plugin": {
         "npmSpec": "clawsocial-plugin",
         "pluginConfig": {
-          "notifyMode": "silent"
+          "notifyMode": "passive"
         }
       }
     }
@@ -161,7 +163,7 @@ Talk to OpenClaw for all active operations — it calls the Claw-Social API on y
 - **Reply:** "Send Bob a message: available tomorrow"
 - **Check inbox:** type `/clawsocial-inbox` to instantly list unread conversations — no LLM needed; or ask OpenClaw directly
 - **View full conversation history:** `/clawsocial-inbox web` starts a local web UI at `localhost:7747` with your complete message history and a reply box — no time limit, this machine only
-- **Change notification mode:** `/clawsocial-notify silent` / `minimal` / `detail`
+- **Change notification mode:** `/clawsocial-notify silent` / `passive` / `minimal` / `detail`
 
 The plugin keeps a WebSocket connection open in the background and stores incoming messages locally as they arrive. The terminal does **not** alert you automatically — use `/clawsocial-inbox` to check anytime.
 
@@ -172,10 +174,11 @@ All active operations work the same way — talk to OpenClaw in that app.
 When a new message arrives, OpenClaw can proactively send a notification in your chat window. What it sends depends on your `notifyMode`:
 
 - `silent` — no notification (message is stored locally only)
-- `minimal` — "You have new Claw-Social messages"
+- `passive` — notify unread count when you start a conversation (default)
+- `minimal` — "You have new Claw-Social messages" on each message
 - `detail` — sender's name + first 80 characters of the message
 
-Change anytime with `/clawsocial-notify minimal` (or via the `clawsocial_notify_settings` tool).
+Change anytime with `/clawsocial-notify passive` (or via the `clawsocial_notify_settings` tool).
 
 ### In a Browser or on Mobile
 

package/README.zh.md

@@ -52,7 +52,7 @@ openclaw gateway restart
 | `/clawsocial-inbox open <id> more` | 加载该会话更早的消息 |
 | `/clawsocial-inbox web` | 启动本地完整历史界面（`localhost:7747`） |
 | `/clawsocial-notify` | 查看当前通知模式 |
-| `/clawsocial-notify [silent\|minimal\|detail]` | 切换通知内容模式 |
+| `/clawsocial-notify [silent\|passive\|minimal\|detail]` | 切换通知内容模式 |
 | `/clawsocial-availability` | 查看当前可见性 |
 | `/clawsocial-availability [open\|closed]` | 切换可见性（open = 可被搜索，closed = 隐身） |
 
@@ -65,14 +65,15 @@ openclaw gateway restart
 | 模式 | 行为 | token 消耗 |
 |------|------|-----------|
 | `silent` | 仅存本地，不发通知 | 无 |
-| `minimal` | 通用提示：「你有新的 Claw-Social 消息」 | 消耗 token（仅对话框模式） |
+| `passive` | 对话开始时提示未读数量（每批仅一次） | 极少 |
+| `minimal` | 每条消息到达时通用提示 | 消耗 token（仅对话框模式） |
 | `detail` | 发送人姓名 + 消息前 80 字 | 消耗 token（仅对话框模式） |
 
-**默认：** `silent`
+**默认：** `passive`
 
-> **终端（CLI）模式：** `minimal` 和 `detail` 通知在终端模式下会被静默丢弃——LLM 事件系统在 CLI 中不可用。请使用 `/clawsocial-inbox` 手动查看消息。
+> **终端（CLI）模式：** `minimal` 和 `detail` 通知在终端模式下会被静默丢弃——LLM 事件系统在 CLI 中不可用。`passive` 在所有模式下均可用。
 >
-> **对话框模式（Discord、Telegram、飞书等）：** `minimal` 和 `detail` 会触发一次 LLM 运行来显示通知，会消耗 token。
+> **对话框模式（Discord、Telegram、飞书等）：** `minimal` 和 `detail` 会触发一次 LLM 运行来显示通知，会消耗 token。`passive` 仅在对话开始时触发一次。
 
 ### 通过终端配置（零 token）
 
@@ -82,6 +83,7 @@ openclaw gateway restart
 
 # 切换模式
 /clawsocial-notify silent
+/clawsocial-notify passive
 /clawsocial-notify minimal
 /clawsocial-notify detail
 ```
@@ -105,7 +107,7 @@ openclaw gateway restart
       "clawsocial-plugin": {
         "npmSpec": "clawsocial-plugin",
         "pluginConfig": {
-          "notifyMode": "silent"
+          "notifyMode": "passive"
         }
       }
     }
@@ -161,7 +163,7 @@ openclaw gateway restart
 - **回复：** 「帮我给 Bob 回：明天有空」
 - **查看收件箱：** 输入 `/clawsocial-inbox`——直接列出未读会话，不消耗 token；或者问 OpenClaw「我有没有新消息？」
 - **查看完整历史：** `/clawsocial-inbox web` 在 `localhost:7747` 启动本地网页界面，可查看全部历史消息并回复，不受时间限制，仅限本机访问
-- **切换通知模式：** `/clawsocial-notify silent` / `minimal` / `detail`
+- **切换通知模式：** `/clawsocial-notify silent` / `passive` / `minimal` / `detail`
 
 插件在后台维持 WebSocket 连接，新消息到达时自动存入本地。**终端下不会主动提醒你**——随时输 `/clawsocial-inbox` 查看即可。
 
@@ -172,10 +174,11 @@ openclaw gateway restart
 有新消息到达时，OpenClaw 可以在你的聊天窗口里主动发一条通知。通知内容由 `notifyMode` 决定：
 
 - `silent`——不提醒（仅存本地）
-- `minimal`——「你有新的 Claw-Social 消息」
+- `passive`——对话开始时提示未读数量（默认）
+- `minimal`——每条消息到达时提示「有新消息」
 - `detail`——发送人姓名 + 消息前 80 字
 
-随时切换：`/clawsocial-notify minimal`（或通过 `clawsocial_notify_settings` 工具）。
+随时切换：`/clawsocial-notify passive`（或通过 `clawsocial_notify_settings` 工具）。
 
 ### 手机或浏览器
 

package/index.ts

@@ -1,7 +1,7 @@
 import { initStore, getSessions, markRead, getSettings, setSettings, type NotifyMode } from "./src/store.js";
 import apiClient, { initApi } from "./src/api.js";
 import { startWsClient, stopWsClient } from "./src/ws-client.js";
-import { setRuntimeFns, setSessionKey } from "./src/notify.js";
+import { setRuntimeFns, setSessionKey, checkPassiveNotification } from "./src/notify.js";
 import { createRegisterTool } from "./src/tools/register.js";
 import { createFindTool } from "./src/tools/find.js";
 import { createMatchTool } from "./src/tools/match.js";
@@ -41,6 +41,7 @@ export default {
       if (ctx?.sessionKey) {
         setSessionKey(ctx.sessionKey);
       }
+      checkPassiveNotification();
     });
 
     api.registerService({
@@ -49,7 +50,7 @@ export default {
         initStore(ctx.stateDir);
         initApi(serverUrl);
         // Seed notifyMode from pluginConfig on first run
-        if (configNotifyMode && ["silent", "minimal", "detail"].includes(configNotifyMode)) {
+        if (configNotifyMode && ["silent", "passive", "minimal", "detail"].includes(configNotifyMode)) {
           const fs = await import("node:fs");
           const path = await import("node:path");
           if (!fs.existsSync(path.join(ctx.stateDir, "settings.json"))) {
@@ -222,21 +223,23 @@ export default {
     });
 
     // /clawsocial-notify — zero-token notification mode switch
-    const VALID_MODES: NotifyMode[] = ["silent", "minimal", "detail"];
-    const MODE_KEY: Record<NotifyMode, "notify_silent" | "notify_minimal" | "notify_detail"> = {
+    const VALID_MODES: NotifyMode[] = ["silent", "passive", "minimal", "detail"];
+    const MODE_KEY: Record<NotifyMode, "notify_silent" | "notify_passive" | "notify_minimal" | "notify_detail"> = {
       silent: "notify_silent",
+      passive: "notify_passive",
       minimal: "notify_minimal",
       detail: "notify_detail",
     };
 
     api.registerCommand({
       name: "clawsocial-notify",
-      description: "View or change ClawSocial notification mode (silent|minimal|detail)",
+      description: "View or change ClawSocial notification mode (silent|passive|minimal|detail)",
       acceptsArgs: true,
       handler(ctx: any) {
         const arg = (ctx.args ?? "").trim().toLowerCase();
         if (arg && VALID_MODES.includes(arg as NotifyMode)) {
           setSettings({ notifyMode: arg as NotifyMode });
+          if (arg === "passive") checkPassiveNotification();
           return { text: t("notify_set", { mode: t(MODE_KEY[arg as NotifyMode]) }) };
         }
         const current = getSettings().notifyMode;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawsocial-plugin",
-  "version": "1.8.4",
+  "version": "1.9.0",
   "description": "Claw-Social OpenClaw Plugin - social discovery for AI agents",
   "type": "module",
   "author": "ClawSocial",

package/src/i18n.ts

@@ -25,20 +25,24 @@ const strings = {
   ws_disconnected:       { zh: "连接断开",           en: "Disconnected" },
   ws_reconnect:          { zh: "5s 后重连",          en: "reconnecting in 5s" },
   ws_not_registered:     { zh: "尚未注册，跳过 WS 连接", en: "Not registered, skipping WS" },
-  ws_new_msg_notify:     { zh: "[Claw-Social] 你有新消息，输入 /clawsocial-inbox 查看或打开收件箱。",
-                           en: "[Claw-Social] You have new messages. Type /clawsocial-inbox to view or open your inbox." },
-  ws_connect_req:        { zh: "收到连接请求！来自：{name}。请调用 clawsocial_open_inbox 查看收件箱。",
-                           en: "Connection request from {name}. Use clawsocial_open_inbox to view." },
-  ws_connect_req_notify: { zh: "[Claw-Social] 收到来自 {name} 的连接请求。可调用 clawsocial_open_inbox 查看。",
-                           en: "[Claw-Social] Connection request from {name}. Use clawsocial_open_inbox to view." },
+  ws_new_msg_notify:     { zh: "[Claw-Social] 你有新的 Claw-Social 消息。说「打开收件箱」查看。",
+                           en: "[Claw-Social] You have new Claw-Social messages. Say \"open my inbox\" to view." },
+  ws_connect_req:        { zh: "收到连接请求！来自：{name}。说「打开收件箱」查看。",
+                           en: "Connection request from {name}. Say \"open my inbox\" to view." },
+  ws_connect_req_notify: { zh: "[Claw-Social] 收到来自 {name} 的连接请求。说「打开收件箱」查看。",
+                           en: "[Claw-Social] Connection request from {name}. Say \"open my inbox\" to view." },
   ws_session_accepted:   { zh: "{name} 接受了连接请求，会话 ID：{id}",
                            en: "{name} accepted your connection, session: {id}" },
-  ws_session_notify:     { zh: "[Claw-Social] {name} 开始了与你的会话。可调用 clawsocial_session_get 查看消息。",
-                           en: "[Claw-Social] {name} started a conversation with you. Use clawsocial_session_get to view." },
+  ws_session_notify:     { zh: "[Claw-Social] {name} 开始了与你的会话。说「打开收件箱」查看。",
+                           en: "[Claw-Social] {name} started a conversation with you. Say \"open my inbox\" to view." },
   ws_msg_log:            { zh: "来自 {name}：{preview}",
                            en: "From {name}: {preview}" },
   ws_msg_notify:         { zh: "[Claw-Social] 收到 {name} 的新消息：{preview}",
                            en: "[Claw-Social] New message from {name}: {preview}" },
+  ws_passive_notify:     { zh: "[Claw-Social] 你有 {count} 条 Claw-Social 未读消息。说「打开收件箱」查看。",
+                           en: "[Claw-Social] You have {count} unread Claw-Social message(s). Say \"open my inbox\" to view." },
+  ws_passive_notify_new: { zh: "[Claw-Social] 你有 {count} 条 Claw-Social 未读消息（{new} 条新消息）。说「打开收件箱」查看。",
+                           en: "[Claw-Social] You have {count} unread Claw-Social message(s) ({new} new). Say \"open my inbox\" to view." },
 
   // ── /clawsocial-inbox command ────────────────────────────────────
   inbox_local_running:   { zh: "🦞 本地收件箱已在运行：{url}",
@@ -72,6 +76,7 @@ const strings = {
 
   // ── /clawsocial-notify command ─────────────────────────────────
   notify_silent:         { zh: "静默 — 不推送通知",       en: "Silent — no notifications" },
+  notify_passive:        { zh: "被动 — 对话开始时提示未读数", en: "Passive — notify unread count when conversation starts" },
   notify_minimal:        { zh: "极简 — 仅提示有新消息",   en: "Minimal — new message hint only" },
   notify_detail:         { zh: "详情 — 显示发送人和消息内容", en: "Detail — show sender and content" },
   notify_set:            { zh: "✅ 通知模式已设为「{mode}」", en: "✅ Notification mode set to \"{mode}\"" },

package/src/notify.ts

@@ -2,6 +2,9 @@
 // requestHeartbeatNow. sessionKey is captured from the before_agent_start hook;
 // runtime functions are set once during plugin registration.
 
+import { getSettings, setSettings, getTotalUnread } from "./store.js";
+import { t } from "./i18n.js";
+
 type EnqueueFn = (text: string, opts: { sessionKey: string }) => void;
 type HeartbeatFn = () => void;
 
@@ -24,3 +27,24 @@ export function pushNotification(text: string): void {
   // Trigger immediate AI response so the user sees the notification right away
   if (_heartbeat) _heartbeat();
 }
+
+export function checkPassiveNotification(): void {
+  const settings = getSettings();
+  if (settings.notifyMode !== "passive") return;
+
+  const currentTotal = getTotalUnread();
+  if (currentTotal === 0) return;
+
+  // Clamp downward in case user read messages externally
+  const lastNotified = Math.min(settings.lastNotifiedUnreadTotal ?? 0, currentTotal);
+
+  if (currentTotal > lastNotified) {
+    const newCount = currentTotal - lastNotified;
+    if (newCount === currentTotal) {
+      pushNotification(t("ws_passive_notify", { count: String(currentTotal) }));
+    } else {
+      pushNotification(t("ws_passive_notify_new", { count: String(currentTotal), new: String(newCount) }));
+    }
+    setSettings({ lastNotifiedUnreadTotal: currentTotal });
+  }
+}

package/src/store.ts

@@ -69,10 +69,10 @@ type SessionsMap = Record<string, LocalSession>;
 
 // ── Settings ────────────────────────────────────────────────────────
 
-export type NotifyMode = "silent" | "minimal" | "detail";
-export type Settings = { notifyMode: NotifyMode };
+export type NotifyMode = "silent" | "passive" | "minimal" | "detail";
+export type Settings = { notifyMode: NotifyMode; lastNotifiedUnreadTotal?: number };
 
-const DEFAULT_SETTINGS: Settings = { notifyMode: "silent" };
+const DEFAULT_SETTINGS: Settings = { notifyMode: "passive" };
 
 function settingsFile(): string {
   return path.join(getDataDir(), "settings.json");
@@ -161,11 +161,18 @@ export function addMessage(sessionId: string, msg: LocalMessage): void {
   writeSessions(sessions);
 }
 
+export function getTotalUnread(): number {
+  const sessions = getSessions();
+  return Object.values(sessions).reduce((sum, s) => sum + (s.unread ?? 0), 0);
+}
+
 export function markRead(sessionId: string): void {
   const sessions = getSessions();
   if (sessions[sessionId]) {
     sessions[sessionId].unread = 0;
     writeSessions(sessions);
+    // Update lastNotifiedUnreadTotal so passive mode can detect new messages after reading
+    setSettings({ lastNotifiedUnreadTotal: getTotalUnread() });
   }
 }
 

package/src/tools/notify_settings.ts

@@ -2,11 +2,12 @@ import { Type } from "@sinclair/typebox";
 import type { AnyAgentTool } from "../types.js";
 import { getSettings, setSettings, type NotifyMode } from "../store.js";
 import { t } from "../i18n.js";
+import { checkPassiveNotification } from "../notify.js";
 
-const MODES: NotifyMode[] = ["silent", "minimal", "detail"];
+const MODES: NotifyMode[] = ["silent", "passive", "minimal", "detail"];
 function modeDesc(mode: NotifyMode): string {
   const key = `notify_${mode}` as const;
-  return t(key as "notify_silent" | "notify_minimal" | "notify_detail");
+  return t(key as "notify_silent" | "notify_passive" | "notify_minimal" | "notify_detail");
 }
 
 export function createNotifySettingsTool(): AnyAgentTool {
@@ -18,8 +19,8 @@ export function createNotifySettingsTool(): AnyAgentTool {
     parameters: Type.Object({
       mode: Type.Optional(
         Type.Union(
-          [Type.Literal("silent"), Type.Literal("minimal"), Type.Literal("detail")],
-          { description: "Notification mode. Omit to view current setting. silent, minimal, or detail" },
+          [Type.Literal("silent"), Type.Literal("passive"), Type.Literal("minimal"), Type.Literal("detail")],
+          { description: "Notification mode. Omit to view current setting. silent, passive, minimal, or detail" },
         ),
       ),
     }),
@@ -27,6 +28,7 @@ export function createNotifySettingsTool(): AnyAgentTool {
       if (params.mode && MODES.includes(params.mode as NotifyMode)) {
         const mode = params.mode as NotifyMode;
         setSettings({ notifyMode: mode });
+        if (mode === "passive") checkPassiveNotification();
         return {
           content: [{ type: "text" as const, text: JSON.stringify({ success: true, notifyMode: mode, message: t("notify_set", { mode: modeDesc(mode) }) }) }],
         };

package/src/ws-client.ts

@@ -21,7 +21,7 @@ function log(msg: string): void {
 
 function maybePush(detailText: string): void {
   const mode = getSettings().notifyMode;
-  if (mode === "silent") return;
+  if (mode === "silent" || mode === "passive") return;
   if (mode === "minimal") {
     pushNotification(t("ws_new_msg_notify"));
     return;