dashclaw 1.9.2 → 1.9.4

package/README.md

@@ -314,6 +314,45 @@ Get root-cause trace for an action, including its assumptions, open loops, paren
 
 ---
 
+## Agent Presence & Health
+
+Monitor agent uptime and status in real-time. Use heartbeats to detect when an agent crashes or loses network connectivity.
+
+### claw.heartbeat(options?)
+Report agent presence and health to the dashboard.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| options.status | string | No | Agent status: 'online', 'busy', 'error' (default: 'online') |
+| options.currentTaskId | string | No | The ID of the task currently being executed |
+| options.metadata | Object | No | Optional key-value pairs for additional context |
+
+**Returns:** `Promise<{ status: string, timestamp: string }>`
+
+### claw.startHeartbeat(options?)
+Start an automatic heartbeat timer that reports 'online' every minute.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| options.interval | number | No | Heartbeat interval in milliseconds (default: 60000 / 1 min) |
+| options.status | string | No | Status to report |
+
+**Example:**
+```javascript
+// Start reporting presence automatically
+claw.startHeartbeat();
+
+// Later, stop it
+claw.stopHeartbeat();
+```
+
+### claw.stopHeartbeat()
+Stop the automatic heartbeat timer.
+
+---
+
 ## Real-Time Flight Recorder
 
 Stream actions live to the dashboard as they happen.

package/dashclaw.js

@@ -681,6 +681,48 @@ class DashClaw {
     return handle;
   }
 
+  /**
+   * Report agent presence and health.
+   * @param {Object} [options]
+   * @param {'online'|'busy'|'error'} [options.status='online']
+   * @param {string} [options.currentTaskId]
+   * @param {Object} [options.metadata]
+   * @returns {Promise<{status: string, timestamp: string}>}
+   */
+  async heartbeat({ status = 'online', currentTaskId, metadata } = {}) {
+    return this._request('/api/agents/heartbeat', 'POST', {
+      agent_id: this.agentId,
+      agent_name: this.agentName,
+      status,
+      current_task_id: currentTaskId,
+      metadata,
+    });
+  }
+
+  /**
+   * Start an automatic heartbeat timer.
+   * @param {Object} [options]
+   * @param {number} [options.interval=60000] - Interval in ms
+   */
+  startHeartbeat(options = {}) {
+    if (this._heartbeatTimer) return;
+    const interval = options.interval || 60000;
+    this.heartbeat(options).catch(() => {}); // Initial heartbeat
+    this._heartbeatTimer = setInterval(() => {
+      this.heartbeat(options).catch(() => {});
+    }, interval);
+  }
+
+  /**
+   * Stop the automatic heartbeat timer.
+   */
+  stopHeartbeat() {
+    if (this._heartbeatTimer) {
+      clearInterval(this._heartbeatTimer);
+      this._heartbeatTimer = null;
+    }
+  }
+
   /**
    * Update the outcome of an existing action.
    * @param {string} actionId - The action_id to update

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dashclaw",
-  "version": "1.9.2",
+  "version": "1.9.4",
   "description": "Full-featured agent toolkit for the DashClaw platform. 96+ methods across 22+ categories for action recording, context management, session handoffs, security scanning, behavior guard, compliance, task routing, identity binding, organization management, webhooks, bulk sync, and more.",
   "type": "module",
   "publishConfig": {