@canonmsg/agent-sdk 0.4.0 → 0.5.0

package/dist/canon-agent.d.ts

@@ -12,6 +12,7 @@ export declare class CanonAgent {
     private agentContext;
     private cachedConversationIds;
     private running;
+    private runtimeHeartbeatTimer;
     constructor(options: CanonAgentOptions);
     on(event: 'message', handler: MessageHandler): void;
     start(): Promise<void>;
@@ -28,6 +29,10 @@ export declare class CanonAgent {
         attachment: import('@canonmsg/core').MediaAttachment;
     }>;
     stop(): Promise<void>;
+    private publishAgentRuntime;
+    private startRuntimeHeartbeat;
+    private stopRuntimeHeartbeat;
+    private clearAgentRuntime;
     private handleMessages;
     private executeHandler;
     static register(options: {

package/dist/canon-agent.js

@@ -1,10 +1,11 @@
-import { CanonClient, FINAL_MESSAGE_HANDOFF_MS, initRTDBAuth, writeSessionState, clearSessionState, writeTurnState, clearTurnState, } from '@canonmsg/core';
+import { CanonClient, FINAL_MESSAGE_HANDOFF_MS, initRTDBAuth, rtdbWrite, writeSessionState, clearSessionState, writeTurnState, clearTurnState, } from '@canonmsg/core';
 import { randomUUID } from 'node:crypto';
 import { AuthManager } from './auth.js';
 import { Debouncer } from './debouncer.js';
 import { PollingManager } from './polling.js';
 import { SessionManager } from './session-manager.js';
 const AUTO_MODE_THRESHOLD = 500;
+const AGENT_RUNTIME_HEARTBEAT_MS = 30_000;
 const SDK_RUNTIME_CAPABILITIES = {
     supportsInterrupt: false,
     supportsQueue: true,
@@ -28,6 +29,7 @@ export class CanonAgent {
     agentContext = null;
     cachedConversationIds = [];
     running = false;
+    runtimeHeartbeatTimer = null;
     constructor(options) {
         this.options = {
             baseUrl: 'https://api-6m6mlelskq-uc.a.run.app',
@@ -109,12 +111,16 @@ export class CanonAgent {
             rtm.setOnAgentContext((ctx) => {
                 this.agentContext = ctx;
             });
+            rtm.setConnectionHandlers({
+                onConnected: () => this.startRuntimeHeartbeat(),
+                onDisconnected: () => this.stopRuntimeHeartbeat(),
+            });
             this.realtimeManager = rtm;
             await rtm.start();
             console.log('[canon-sdk] SSE stream started');
         }
         else {
-            this.pollingManager = new PollingManager(this.apiClient, this.debouncer, agentId, this.options.pollingIntervalMs);
+            this.pollingManager = new PollingManager(this.apiClient, this.debouncer, agentId, this.options.pollingIntervalMs, () => this.startRuntimeHeartbeat(), () => this.stopRuntimeHeartbeat());
             await this.pollingManager.start();
             console.log(`[canon-sdk] Polling started (interval: ${this.options.pollingIntervalMs}ms)`);
         }
@@ -155,6 +161,7 @@ export class CanonAgent {
                 clearTurnState(id, this.agentId).catch(() => { });
             }
         }
+        await this.clearAgentRuntime();
         this.pollingManager?.stop();
         this.realtimeManager?.stop();
         this.sessionManager?.destroy();
@@ -162,6 +169,36 @@ export class CanonAgent {
         this.debouncer.destroy();
         console.log('[canon-sdk] Stopped');
     }
+    async publishAgentRuntime() {
+        if (!this.agentId)
+            return;
+        await rtdbWrite(`/agent-runtime/${this.agentId}`, {
+            clientType: this.options.clientType ?? 'generic',
+            hostMode: false,
+            updatedAt: { '.sv': 'timestamp' },
+        });
+    }
+    startRuntimeHeartbeat() {
+        void this.publishAgentRuntime();
+        if (this.runtimeHeartbeatTimer)
+            return;
+        this.runtimeHeartbeatTimer = setInterval(() => {
+            void this.publishAgentRuntime();
+        }, AGENT_RUNTIME_HEARTBEAT_MS);
+        this.runtimeHeartbeatTimer.unref?.();
+    }
+    stopRuntimeHeartbeat() {
+        if (this.runtimeHeartbeatTimer) {
+            clearInterval(this.runtimeHeartbeatTimer);
+            this.runtimeHeartbeatTimer = null;
+        }
+        void this.clearAgentRuntime();
+    }
+    async clearAgentRuntime() {
+        if (!this.agentId)
+            return;
+        await rtdbWrite(`/agent-runtime/${this.agentId}`, null).catch(() => { });
+    }
     async handleMessages(conversationId, messages) {
         if (!this.handler) {
             console.warn(`[canon-sdk] No message handler registered — messages for ${conversationId} dropped. Call agent.on('message', handler) before starting.`);

package/dist/polling.d.ts

@@ -5,10 +5,12 @@ export declare class PollingManager {
     private debouncer;
     private agentId;
     private pollingIntervalMs;
+    private onHealthy;
+    private onUnhealthy;
     private lastSeenTimestamps;
     private pollTimer;
     private running;
-    constructor(apiClient: CanonClient, debouncer: Debouncer, agentId: string, pollingIntervalMs: number);
+    constructor(apiClient: CanonClient, debouncer: Debouncer, agentId: string, pollingIntervalMs: number, onHealthy?: () => void, onUnhealthy?: () => void);
     start(): Promise<void>;
     private poll;
     private findActiveConversations;

package/dist/polling.js

@@ -5,14 +5,18 @@ export class PollingManager {
     debouncer;
     agentId;
     pollingIntervalMs;
+    onHealthy;
+    onUnhealthy;
     lastSeenTimestamps = new Map();
     pollTimer = null;
     running = false;
-    constructor(apiClient, debouncer, agentId, pollingIntervalMs) {
+    constructor(apiClient, debouncer, agentId, pollingIntervalMs, onHealthy, onUnhealthy) {
         this.apiClient = apiClient;
         this.debouncer = debouncer;
         this.agentId = agentId;
         this.pollingIntervalMs = pollingIntervalMs;
+        this.onHealthy = onHealthy ?? null;
+        this.onUnhealthy = onUnhealthy ?? null;
     }
     async start() {
         this.running = true;
@@ -22,6 +26,7 @@ export class PollingManager {
         for (const convo of conversations) {
             this.lastSeenTimestamps.set(convo.id, now);
         }
+        this.onHealthy?.();
         // Start polling
         this.pollTimer = setInterval(() => this.poll(), this.pollingIntervalMs);
     }
@@ -30,6 +35,7 @@ export class PollingManager {
             return;
         try {
             const conversations = await this.apiClient.getConversations();
+            this.onHealthy?.();
             const activeConvos = this.findActiveConversations(conversations);
             await Promise.all(activeConvos.map(async (convo) => {
                 try {
@@ -67,6 +73,7 @@ export class PollingManager {
             }));
         }
         catch (err) {
+            this.onUnhealthy?.();
             console.error('[canon-sdk] Polling error:', err);
         }
     }

package/dist/realtime.d.ts

@@ -15,8 +15,14 @@ export declare class RealtimeManager {
     private knownConversationIds;
     private discoveryTimer;
     private onAgentContext;
+    private onConnected;
+    private onDisconnected;
     constructor(apiKey: string, debouncer: Debouncer, agentId: string, streamUrl?: string, apiClient?: CanonClient);
     setOnAgentContext(cb: (ctx: AgentContext) => void): void;
+    setConnectionHandlers(handlers: {
+        onConnected?: () => void;
+        onDisconnected?: () => void;
+    }): void;
     start(): Promise<void>;
     stop(): void;
     private discoverNewConversations;

package/dist/realtime.js

@@ -17,6 +17,8 @@ export class RealtimeManager {
     knownConversationIds = new Set();
     discoveryTimer = null;
     onAgentContext = null;
+    onConnected = null;
+    onDisconnected = null;
     constructor(apiKey, debouncer, agentId, streamUrl, apiClient) {
         this.debouncer = debouncer;
         this.agentId = agentId;
@@ -54,6 +56,10 @@ export class RealtimeManager {
                 },
                 onConnected: () => {
                     // Reset backoff is handled internally by CanonStream
+                    this.onConnected?.();
+                },
+                onDisconnected: () => {
+                    this.onDisconnected?.();
                 },
                 onError: (err) => {
                     console.error('[canon-sdk] SSE error:', err.message);
@@ -64,6 +70,10 @@ export class RealtimeManager {
     setOnAgentContext(cb) {
         this.onAgentContext = cb;
     }
+    setConnectionHandlers(handlers) {
+        this.onConnected = handlers.onConnected ?? null;
+        this.onDisconnected = handlers.onDisconnected ?? null;
+    }
     async start() {
         this.running = true;
         // Snapshot current conversations
@@ -89,6 +99,7 @@ export class RealtimeManager {
             this.discoveryTimer = null;
         }
         this.stream.stop();
+        this.onDisconnected?.();
     }
     // ── Conversation discovery ─────────────────────────────────────────
     async discoverNewConversations() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-sdk",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Canon Agent SDK — build AI agents that participate in Canon conversations",
   "type": "module",
   "main": "dist/index.js",
@@ -23,7 +23,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@canonmsg/core": "^0.4.0"
+    "@canonmsg/core": "^0.5.0"
   },
   "publishConfig": {
     "access": "public"