@hzhipeng/heartbeat-notify 1.0.1

package/README.md

@@ -0,0 +1,23 @@
+# Heartbeat Notify
+
+OpenClaw native plugin that exposes `heartbeat_notify` for main-agent heartbeat runs.
+
+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.

package/index.js

@@ -0,0 +1,309 @@
+"use strict";
+
+const http = require("http");
+const https = require("https");
+const os = require("os");
+
+const PLUGIN_ID = "heartbeat-notify";
+const TOOL_NAME = "heartbeat_notify";
+const DEFAULT_GATEWAY_URL = "http://claw-gateway:8080";
+const DEFAULT_TIMEOUT_MS = 30 * 1000;
+const MAX_TIMEOUT_MS = 120 * 1000;
+const NOTIFY_PATH = "/openclaw-gateway/be/internal/heartbeat/notify";
+
+function trimString(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function boolValue(value) {
+  return value === true || value === "true" || value === "1";
+}
+
+function numberFromEnv(name, fallback, maxValue) {
+  const raw = Number(process.env[name]);
+  if (!Number.isFinite(raw) || raw <= 0) {
+    return fallback;
+  }
+  return maxValue > 0 ? Math.min(raw, maxValue) : raw;
+}
+
+function gatewayURL() {
+  return (
+    trimString(process.env.HEARTBEAT_NOTIFY_GATEWAY_URL) ||
+    trimString(process.env.CLAW_GATEWAY_URL) ||
+    DEFAULT_GATEWAY_URL
+  ).replace(/\/+$/u, "");
+}
+
+function authHeaders() {
+  const apiKey = trimString(process.env.CLAW_GATEWAY_API_KEY);
+  const podToken = trimString(process.env.OPENCLAW_GATEWAY_TOKEN);
+  const headers = {};
+  if (apiKey) {
+    headers["X-API-Key"] = apiKey;
+  }
+  if (podToken) {
+    headers["X-OpenClaw-Token"] = podToken;
+  }
+  return headers;
+}
+
+function requestTimeoutMS() {
+  return numberFromEnv("HEARTBEAT_NOTIFY_TIMEOUT_MS", DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS);
+}
+
+function hostname() {
+  return trimString(process.env.OPENCLAW_POD_NAME) || trimString(process.env.HOSTNAME) || os.hostname();
+}
+
+function defaultBotID() {
+  return trimString(process.env.botID) || trimString(process.env.BOT_ID);
+}
+
+function defaultReleaseName() {
+  return (
+    trimString(process.env.HEARTBEAT_NOTIFY_RELEASE_NAME) ||
+    trimString(process.env.MANAGED_CRON_RELEASE_NAME) ||
+    trimString(process.env.botID)
+  );
+}
+
+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) {
+  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"),
+    targetType: targetString(params, "target_type", "targetType"),
+    conversationType: targetString(params, "conversation_type", "conversationType"),
+    conversationId: targetString(params, "conversation_id", "conversationId"),
+    groupId: targetString(params, "group_id", "groupId"),
+    senderId: targetString(params, "sender_id", "senderId"),
+    lobsterId: targetString(params, "lobster_id", "lobsterId"),
+    botId: targetString(params, "bot_id", "botId") || defaultBotID(),
+    agentId,
+    sessionKey,
+    physicalReleaseName:
+      targetString(params, "physical_release_name", "physicalReleaseName") || defaultReleaseName(),
+    podName: targetString(params, "pod_name", "podName") || hostname(),
+    topicKey: targetString(params, "topic_key", "topicKey"),
+    dedupeKey: targetString(params, "dedupe_key", "dedupeKey"),
+    reason: targetString(params, "reason", "reason"),
+  };
+}
+
+function requestJSON(path, body) {
+  return new Promise((resolve, reject) => {
+    const url = new URL(path, `${gatewayURL()}/`);
+    const payload = JSON.stringify(body);
+    const transport = url.protocol === "https:" ? https : http;
+    const timeout = requestTimeoutMS();
+    const req = transport.request(
+      {
+        method: "POST",
+        hostname: url.hostname,
+        port: url.port || (url.protocol === "https:" ? 443 : 80),
+        path: `${url.pathname}${url.search}`,
+        headers: {
+          Accept: "application/json",
+          "Content-Type": "application/json",
+          "Content-Length": Buffer.byteLength(payload),
+          ...authHeaders(),
+        },
+        timeout,
+      },
+      (res) => {
+        const chunks = [];
+        res.on("data", (chunk) => chunks.push(chunk));
+        res.on("end", () => {
+          const text = Buffer.concat(chunks).toString("utf8");
+          let data = null;
+          if (text) {
+            try {
+              data = JSON.parse(text);
+            } catch (_err) {
+              reject(new Error(`invalid JSON response from gateway: ${text.slice(0, 300)}`));
+              return;
+            }
+          }
+          if (res.statusCode < 200 || res.statusCode >= 300) {
+            reject(new Error(`gateway returned ${res.statusCode}: ${text.slice(0, 300)}`));
+            return;
+          }
+          resolve(data);
+        });
+      },
+    );
+    req.on("timeout", () => {
+      req.destroy(new Error(`gateway request timed out after ${timeout}ms`));
+    });
+    req.on("error", reject);
+    req.write(payload);
+    req.end();
+  });
+}
+
+async function heartbeatNotify(params, ctx) {
+  const request = buildRequest(params || {}, ctx);
+  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;
+  return {
+    ok: delivered,
+    request: {
+      notify: request.notify,
+      groupId: request.groupId,
+      agentId: request.agentId,
+      sessionKey: request.sessionKey,
+      topicKey: request.topicKey,
+      dedupeKey: request.dedupeKey,
+    },
+    gateway: response,
+  };
+}
+
+function toolResult(result) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    details: result,
+  };
+}
+
+const parameters = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    notify: {
+      type: "boolean",
+      description: "Set true only when HEARTBEAT.md decides a user-visible notification must be delivered. Set false for no-op heartbeat checks.",
+    },
+    text: {
+      type: "string",
+      description: "User-visible notification text. Required when notify=true. Do not put this text in the final heartbeat reply.",
+    },
+    group_id: {
+      type: "string",
+      description: "Optional group ID for group notifications. Omit for the owner direct chat.",
+    },
+    physical_release_name: {
+      type: "string",
+      description: "Optional physical OpenClaw release name for tracing.",
+    },
+    pod_name: {
+      type: "string",
+      description: "Optional pod name for tracing.",
+    },
+    topic_key: {
+      type: "string",
+      description: "Optional stable topic key for the notification.",
+    },
+    dedupe_key: {
+      type: "string",
+      description: "Optional idempotency key. Same key produces same heartbeat message id.",
+    },
+    reason: {
+      type: "string",
+      description: "Short internal reason for why this notification is needed.",
+    },
+  },
+  required: ["notify"],
+};
+
+const plugin = {
+  id: PLUGIN_ID,
+  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.",
+      parameters,
+      async execute(_callId, params, _signal, _onUpdate, ctx) {
+        return toolResult(await heartbeatNotify(params || {}, ctx));
+      },
+    });
+  },
+};
+
+plugin.__test = {
+  buildRequest,
+  contextString,
+  defaultBotID,
+  firstString,
+  gatewayURL,
+  heartbeatNotify,
+  requestJSON,
+};
+
+module.exports = plugin;
+module.exports.default = plugin;

package/openclaw-plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "heartbeat-notify",
+  "version": "1.0.1",
+  "npm_package": "@hzhipeng/heartbeat-notify",
+  "description": "Heartbeat notify plugin: expose heartbeat_notify as an OpenClaw native tool",
+  "openclaw_config": {
+    "plugins": {
+      "entries": {
+        "heartbeat-notify": {}
+      }
+    }
+  },
+  "contracts": {
+    "tools": [
+      "heartbeat_notify"
+    ]
+  }
+}

package/openclaw.plugin.json

@@ -0,0 +1,16 @@
+{
+  "id": "heartbeat-notify",
+  "name": "Heartbeat Notify",
+  "description": "Native tool for delivering structured main-agent heartbeat notifications through claw-gateway.",
+  "version": "1.0.1",
+  "contracts": {
+    "tools": [
+      "heartbeat_notify"
+    ]
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@hzhipeng/heartbeat-notify",
+  "version": "1.0.1",
+  "description": "OpenClaw main-agent heartbeat notification plugin for Gateway delivery",
+  "keywords": [
+    "openclaw",
+    "plugin",
+    "heartbeat"
+  ],
+  "license": "MIT",
+  "main": "index.js",
+  "scripts": {
+    "test": "node test/index.test.js"
+  },
+  "files": [
+    "index.js",
+    "openclaw.plugin.json",
+    "openclaw-plugin.json",
+    "README.md",
+    "test/"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./index.js"
+    ],
+    "contracts": {
+      "tools": [
+        "heartbeat_notify"
+      ]
+    }
+  },
+  "engines": {
+    "node": ">=16"
+  }
+}

package/test/index.test.js

@@ -0,0 +1,70 @@
+"use strict";
+
+const assert = require("assert");
+const fs = require("fs");
+const path = require("path");
+
+const plugin = require("../index.js");
+
+const ROOT = path.resolve(__dirname, "..");
+
+function readJSON(name) {
+  return JSON.parse(fs.readFileSync(path.join(ROOT, name), "utf8"));
+}
+
+const expectedTools = ["heartbeat_notify"];
+
+{
+  const runtimeManifest = readJSON("openclaw.plugin.json");
+  const gatewayManifest = readJSON("openclaw-plugin.json");
+  const pkg = readJSON("package.json");
+
+  assert.deepStrictEqual(runtimeManifest.contracts.tools, expectedTools);
+  assert.deepStrictEqual(gatewayManifest.contracts.tools, expectedTools);
+  assert.deepStrictEqual(pkg.openclaw.contracts.tools, expectedTools);
+}
+
+{
+  const oldEnv = { ...process.env };
+  process.env.botID = "lobster_1";
+  process.env.HOSTNAME = "pod-a";
+  try {
+    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",
+      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.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");