@nullbridge/sdk 1.0.3 → 1.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nullbridge/sdk",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "NullBridge AI Agent Identity Governance SDK",
   "main": "src/index.js",
   "types": "src/index.d.ts",

package/src/agents.js

@@ -9,34 +9,36 @@ class AgentRegistry {
   constructor(config, http) {
     this._config = config;
     this._http   = http;
-    this._agents = new Map(); // local cache
+    this._agents = new Map();
   }
 
   /**
    * Register a new AI agent with NullBridge.
    *
    * @param {object} options
+   * @param {string} [options.id]        - Stable unique identifier. Auto-generated if omitted.
    * @param {string} options.name        - Human-readable agent name (e.g. 'claims-processor')
    * @param {string} options.type        - Agent type: 'llm' | 'rpa' | 'workflow' | 'custom'
    * @param {string} [options.model]     - Model name (e.g. 'gpt-4o', 'claude-3-5-sonnet')
-   * @param {string[]} [options.scopes]  - What this agent is allowed to do (e.g. ['read:claims', 'write:reports'])
-   * @param {object} [options.metadata]  - Any additional metadata
+   * @param {string[]} [options.scopes]  - Permission scopes (e.g. ['read:claims', 'write:reports'])
+   * @param {object} [options.metadata]  - Additional metadata
+   * @param {number} [options.heartbeatInterval] - Heartbeat interval in ms (default: 60000)
    * @returns {Promise<Agent>}
    */
   async register(options = {}) {
     if (!options.name) throw new Error('[NullBridge] agent.name is required');
     if (!options.type) throw new Error('[NullBridge] agent.type is required');
 
-    const agentId = this._generateAgentId(options.name);
+    const agentId = options.id || this._generateAgentId(options.name);
 
     const payload = {
-      id:         agentId,
-      name:       options.name,
-      type:       options.type,
-      model:      options.model     || null,
-      scopes:     options.scopes    || [],
-      metadata:   options.metadata  || {},
-      sdk_version: '1.0.0',
+      id:            agentId,
+      name:          options.name,
+      type:          options.type,
+      model:         options.model    || null,
+      scopes:        options.scopes   || [],
+      metadata:      options.metadata || {},
+      sdk_version:   '1.0.3',
       registered_at: Math.floor(Date.now() / 1000),
     };
 
@@ -47,13 +49,20 @@ class AgentRegistry {
         { license_key: this._config.licenseKey, agent: payload }
       );
 
-      const agent = status === 200 || status === 201
+      const agent = (status === 200 || status === 201)
         ? { ...payload, ...body.agent, _registered: true }
         : { ...payload, _registered: false, _local: true };
 
       this._agents.set(agentId, agent);
       console.info(`[NullBridge] Agent registered: ${options.name} (${agentId})`);
-      return new Agent(agent, this._config, this._http);
+
+      const instance = new Agent(agent, this._config, this._http);
+
+      // Start heartbeat automatically
+      const heartbeatMs = options.heartbeatInterval || 60000;
+      instance.startHeartbeat(heartbeatMs);
+
+      return instance;
 
     } catch (err) {
       // API unreachable — register locally and continue
@@ -103,9 +112,10 @@ class AgentRegistry {
  */
 class Agent {
   constructor(data, config, http) {
-    this._data   = data;
-    this._config = config;
-    this._http   = http;
+    this._data             = data;
+    this._config           = config;
+    this._http             = http;
+    this._heartbeatTimer   = null;
 
     // Expose agent properties
     this.id       = data.id;
@@ -166,9 +176,10 @@ class Agent {
   }
 
   /**
-   * Deregister this agent — revokes its identity and credentials
+   * Deregister this agent — revokes its identity and stops heartbeat
    */
   async deregister() {
+    this.stopHeartbeat();
     try {
       await this._http.post(
         this._config.apiUrl,
@@ -181,6 +192,50 @@ class Agent {
     }
   }
 
+  /**
+   * Send a heartbeat to update last_seen in the dashboard.
+   * Called automatically by startHeartbeat() — you don't need to call this manually.
+   */
+  async heartbeat() {
+    try {
+      await this._http.post(
+        this._config.apiUrl,
+        `/sdk/agents/${this.id}/heartbeat`,
+        { license_key: this._config.licenseKey }
+      );
+      if (this._config.debug) {
+        console.debug(`[NullBridge] Heartbeat sent: ${this.name}`);
+      }
+    } catch {
+      // Silently fail — heartbeat is best-effort
+    }
+  }
+
+  /**
+   * Start sending periodic heartbeats to keep last_seen current in the dashboard.
+   * Called automatically after register(). You only need this if you stopped it manually.
+   *
+   * @param {number} [intervalMs=60000] - How often to ping in milliseconds
+   */
+  startHeartbeat(intervalMs = 60000) {
+    if (this._heartbeatTimer) return; // already running
+    // Send immediately on start
+    this.heartbeat();
+    this._heartbeatTimer = setInterval(() => this.heartbeat(), intervalMs);
+    // Allow Node.js to exit even if heartbeat is still running
+    if (this._heartbeatTimer.unref) this._heartbeatTimer.unref();
+  }
+
+  /**
+   * Stop sending heartbeats. Called automatically by deregister() and shutdown().
+   */
+  stopHeartbeat() {
+    if (this._heartbeatTimer) {
+      clearInterval(this._heartbeatTimer);
+      this._heartbeatTimer = null;
+    }
+  }
+
   toJSON() {
     return {
       id: this.id, name: this.name, type: this.type,