@hzhipeng/heartbeat-notify 1.0.1 → 2026.7.1

package/README.md

@@ -6,18 +6,4 @@ The tool posts structured heartbeat notification decisions to:
 
 `/openclaw-gateway/be/internal/heartbeat/notify`
 
-Use `notify=false` for no-op heartbeat checks. Use `notify=true` only when `HEARTBEAT.md` has selected user-visible text.
-
-Minimal call shape:
-
-```json
-{ "notify": true, "text": "Reminder text" }
-```
-
-For group notifications, also pass `group_id`:
-
-```json
-{ "notify": true, "text": "Group reminder text", "group_id": "group-id" }
-```
-
-Do not ask the model to provide `conversation_id`, `sender_id`, `lobster_id`, or `bot_id`. Gateway resolves the delivery route from the current agent/session context.
+Use `notify=false` for no-op heartbeat checks. Use `notify=true` only when `HEARTBEAT.md` has selected a concrete target and user-visible text.

package/index.js

@@ -72,42 +72,8 @@ function targetString(params, snake, camel) {
   return trimString(params[snake]) || trimString(params[camel]);
 }
 
-function contextString(source, ...keys) {
-  if (!source || typeof source !== "object") {
-    return "";
-  }
-  for (const key of keys) {
-    const value = trimString(source[key]);
-    if (value) {
-      return value;
-    }
-  }
-  return "";
-}
-
-function firstString(...values) {
-  for (const value of values) {
-    const text = trimString(value);
-    if (text) {
-      return text;
-    }
-  }
-  return "";
-}
-
-function buildRequest(params, ctx) {
+function buildRequest(params) {
   const notify = boolValue(params.notify);
-  const safeCtx = ctx && typeof ctx === "object" ? ctx : {};
-  const agentId = firstString(
-    targetString(params, "_agent_id", "_agentId"),
-    targetString(params, "agent_id", "agentId"),
-    contextString(safeCtx, "agentId", "agent_id"),
-  );
-  const sessionKey = firstString(
-    targetString(params, "_session_key", "_sessionKey"),
-    targetString(params, "session_key", "sessionKey"),
-    contextString(safeCtx, "sessionKey", "session_key", "sessionId", "session_id"),
-  );
   return {
     notify,
     text: targetString(params, "text", "text"),
@@ -118,8 +84,8 @@ function buildRequest(params, ctx) {
     senderId: targetString(params, "sender_id", "senderId"),
     lobsterId: targetString(params, "lobster_id", "lobsterId"),
     botId: targetString(params, "bot_id", "botId") || defaultBotID(),
-    agentId,
-    sessionKey,
+    agentId: targetString(params, "agent_id", "agentId"),
+    sessionKey: targetString(params, "session_key", "sessionKey"),
     physicalReleaseName:
       targetString(params, "physical_release_name", "physicalReleaseName") || defaultReleaseName(),
     podName: targetString(params, "pod_name", "podName") || hostname(),
@@ -180,8 +146,8 @@ function requestJSON(path, body) {
   });
 }
 
-async function heartbeatNotify(params, ctx) {
-  const request = buildRequest(params || {}, ctx);
+async function heartbeatNotify(params) {
+  const request = buildRequest(params || {});
   const response = await requestJSON(NOTIFY_PATH, request);
   const gatewayData = response && typeof response === "object" ? response.data : null;
   const delivered = gatewayData && typeof gatewayData === "object" ? gatewayData.ok !== false : true;
@@ -189,9 +155,9 @@ async function heartbeatNotify(params, ctx) {
     ok: delivered,
     request: {
       notify: request.notify,
-      groupId: request.groupId,
+      conversationType: request.conversationType,
+      conversationId: request.conversationId,
       agentId: request.agentId,
-      sessionKey: request.sessionKey,
       topicKey: request.topicKey,
       dedupeKey: request.dedupeKey,
     },
@@ -218,9 +184,43 @@ const parameters = {
       type: "string",
       description: "User-visible notification text. Required when notify=true. Do not put this text in the final heartbeat reply.",
     },
+    target_type: {
+      type: "string",
+      enum: ["direct", "group"],
+      description: "Target conversation type. Same as conversation_type.",
+    },
+    conversation_type: {
+      type: "string",
+      enum: ["direct", "group"],
+      description: "Palz conversation type.",
+    },
+    conversation_id: {
+      type: "string",
+      description: "Palz conversation_id to deliver into.",
+    },
     group_id: {
       type: "string",
-      description: "Optional group ID for group notifications. Omit for the owner direct chat.",
+      description: "Optional Palz group_id for group notifications.",
+    },
+    sender_id: {
+      type: "string",
+      description: "Owner/user ID from the selected route.",
+    },
+    lobster_id: {
+      type: "string",
+      description: "Bot/lobster ID from the selected route.",
+    },
+    bot_id: {
+      type: "string",
+      description: "Optional bot_id. Defaults to current pod botID.",
+    },
+    agent_id: {
+      type: "string",
+      description: "Logical main agent ID that produced the heartbeat.",
+    },
+    session_key: {
+      type: "string",
+      description: "Optional heartbeat session key for tracing.",
     },
     physical_release_name: {
       type: "string",
@@ -251,45 +251,13 @@ const plugin = {
   name: "Heartbeat Notify",
   description: "Deliver structured main-agent heartbeat notifications through claw-gateway.",
   register(api) {
-    if (api && typeof api.on === "function") {
-      api.on("before_tool_call", async (event, ctx) => {
-        const safeEvent = event && typeof event === "object" ? event : {};
-        const toolName = trimString(safeEvent.toolName || safeEvent.tool_name || safeEvent.name);
-        if (toolName !== TOOL_NAME) {
-          return undefined;
-        }
-        const params = safeEvent.params && typeof safeEvent.params === "object" ? safeEvent.params : {};
-        const safeCtx = ctx && typeof ctx === "object" ? ctx : {};
-        const nextParams = { ...params };
-        const agentId = firstString(
-          targetString(nextParams, "_agent_id", "_agentId"),
-          targetString(nextParams, "agent_id", "agentId"),
-          contextString(safeCtx, "agentId", "agent_id"),
-          contextString(safeEvent, "agentId", "agent_id"),
-        );
-        const sessionKey = firstString(
-          targetString(nextParams, "_session_key", "_sessionKey"),
-          targetString(nextParams, "session_key", "sessionKey"),
-          contextString(safeCtx, "sessionKey", "session_key", "sessionId", "session_id"),
-          contextString(safeEvent, "sessionKey", "session_key", "sessionId", "session_id"),
-        );
-        if (agentId) {
-          nextParams._agent_id = agentId;
-        }
-        if (sessionKey) {
-          nextParams._session_key = sessionKey;
-        }
-        return { params: nextParams };
-      });
-    }
-
     api.registerTool({
       name: TOOL_NAME,
       description:
-        "Send or no-op a main-agent heartbeat notification. Use only from HEARTBEAT.md. If notify=true, provide text and optional group_id only; omit group_id for the owner direct chat. Gateway resolves sender, bot, lobster, and conversation route. If target is missing or uncertain, call with notify=false. After this tool call, the final heartbeat reply must still be exactly HEARTBEAT_OK.",
+        "Send or no-op a main-agent heartbeat notification. Use only from HEARTBEAT.md. If notify=true, provide text plus conversation_type, conversation_id, sender_id, lobster_id, and bot_id/current botID. If target is missing or uncertain, call with notify=false. After this tool call, the final heartbeat reply must still be exactly HEARTBEAT_OK.",
       parameters,
-      async execute(_callId, params, _signal, _onUpdate, ctx) {
-        return toolResult(await heartbeatNotify(params || {}, ctx));
+      async execute(_callId, params) {
+        return toolResult(await heartbeatNotify(params || {}));
       },
     });
   },
@@ -297,9 +265,7 @@ const plugin = {
 
 plugin.__test = {
   buildRequest,
-  contextString,
   defaultBotID,
-  firstString,
   gatewayURL,
   heartbeatNotify,
   requestJSON,

package/openclaw-plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "heartbeat-notify",
-  "version": "1.0.1",
+  "version": "2026.7.1",
   "npm_package": "@hzhipeng/heartbeat-notify",
   "description": "Heartbeat notify plugin: expose heartbeat_notify as an OpenClaw native tool",
   "openclaw_config": {

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "heartbeat-notify",
   "name": "Heartbeat Notify",
   "description": "Native tool for delivering structured main-agent heartbeat notifications through claw-gateway.",
-  "version": "1.0.1",
+  "version": "2026.7.1",
   "contracts": {
     "tools": [
       "heartbeat_notify"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hzhipeng/heartbeat-notify",
-  "version": "1.0.1",
+  "version": "2026.7.1",
   "description": "OpenClaw main-agent heartbeat notification plugin for Gateway delivery",
   "keywords": [
     "openclaw",

package/test/index.test.js

@@ -32,39 +32,22 @@ const expectedTools = ["heartbeat_notify"];
     const req = plugin.__test.buildRequest({
       notify: true,
       text: "hello",
-      group_id: "group-1",
-      _agent_id: "user-1-main",
-      _session_key: "agent:user-1-main:heartbeat",
+      conversation_type: "direct",
+      conversation_id: "conv-1",
+      sender_id: "user-1",
+      lobster_id: "lobster_1",
+      agent_id: "user-1-main",
       dedupe_key: "topic-1",
     });
     assert.strictEqual(req.notify, true);
     assert.strictEqual(req.botId, "lobster_1");
     assert.strictEqual(req.podName, "pod-a");
-    assert.strictEqual(req.groupId, "group-1");
-    assert.strictEqual(req.agentId, "user-1-main");
-    assert.strictEqual(req.sessionKey, "agent:user-1-main:heartbeat");
+    assert.strictEqual(req.conversationType, "direct");
+    assert.strictEqual(req.conversationId, "conv-1");
     assert.strictEqual(req.dedupeKey, "topic-1");
   } finally {
     process.env = oldEnv;
   }
 }
 
-{
-  const req = plugin.__test.buildRequest(
-    {
-      notify: true,
-      text: "hello direct",
-    },
-    {
-      agentId: "user-a0bd-main",
-      sessionKey: "agent:user-a0bd-main:main",
-    },
-  );
-  assert.strictEqual(req.notify, true);
-  assert.strictEqual(req.text, "hello direct");
-  assert.strictEqual(req.agentId, "user-a0bd-main");
-  assert.strictEqual(req.sessionKey, "agent:user-a0bd-main:main");
-  assert.strictEqual(req.groupId, "");
-}
-
 console.log("heartbeat-notify tests passed");