@canonmsg/agent-sdk 0.3.0 → 0.5.0

package/README.md

@@ -75,7 +75,7 @@ The `message` event handler receives a context object with:
 | `conversation` | `SDKConversation` | Full conversation metadata |
 | `reply` | `(text: string, options?) => Promise<{ messageId: string }>` | Convenience alias for `replyFinal` |
 | `replyFinal` | `(text: string, options?) => Promise<{ messageId: string }>` | Send the durable final reply for a turn |
-| `replyProgress` | `(text: string, options?) => Promise<{ messageId: string }>` | Send a durable progress update during a turn |
+| `replyProgress` | `(text: string, options?) => Promise<{ turnId: string; durable: boolean; messageId: string \| null }>` | Update the live turn progress; add `durable: true` to also persist it |
 | `agent` | `AgentContext` | Trusted Canon agent identity and access context |
 | `session` | `SessionInfo \| undefined` | Per-conversation queue/session state when sessions are enabled |
 | `turn` | `TurnController \| undefined` | Live turn-state helpers for thinking/streaming/tool/waiting-input |
@@ -178,3 +178,5 @@ While a handler runs, the SDK automatically publishes Canon turn state and clear
 - `setWaitingInput(text?)`
 
 `setWaitingInput()` keeps the turn open in `waiting_input` and optionally sends a control message to the conversation so Canon clients can render “reply to continue” correctly.
+
+`replyProgress()` is ephemeral by default: it updates the live RTDB turn preview without adding a permanent Firestore message. In that mode it returns `{ turnId, durable: false, messageId: null }`; pass `{ durable: true }` when you intentionally want progress chatter to remain in history and receive a real Firestore message ID back.

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,17 +1,21 @@
-import { CanonClient, 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,
     supportsInterleave: false,
     supportsRequiresAction: false,
-    supportsNonFinalPermanentMessages: true,
+    supportsNonFinalPermanentMessages: false,
 };
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 export class CanonAgent {
     options;
     apiClient;
@@ -25,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',
@@ -106,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)`);
         }
@@ -152,6 +161,7 @@ export class CanonAgent {
                 clearTurnState(id, this.agentId).catch(() => { });
             }
         }
+        await this.clearAgentRuntime();
         this.pollingManager?.stop();
         this.realtimeManager?.stop();
         this.sessionManager?.destroy();
@@ -159,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.`);
@@ -251,7 +291,6 @@ export class CanonAgent {
                     await this.apiClient.setTyping(conversationId, true, 'typing');
                 }
                 catch { }
-                await writeTurn('completed');
                 const result = await this.apiClient.sendMessage(conversationId, text, {
                     ...(options ?? {}),
                     metadata: {
@@ -261,27 +300,29 @@ export class CanonAgent {
                         turnComplete: true,
                     },
                 });
+                await sleep(FINAL_MESSAGE_HANDOFF_MS);
                 try {
                     await this.apiClient.setTyping(conversationId, false);
                 }
                 catch { }
-                try {
-                    await this.apiClient.clearStreaming(conversationId);
-                }
-                catch { }
                 return result;
             };
             const replyProgress = async (text, options) => {
                 await setLiveState('streaming', text, 'streaming');
-                return this.apiClient.sendMessage(conversationId, text, {
-                    ...(options ?? {}),
+                if (!options?.durable) {
+                    return { turnId, durable: false, messageId: null };
+                }
+                const { durable: _durable, ...sendOptions } = options;
+                const result = await this.apiClient.sendMessage(conversationId, text, {
+                    ...sendOptions,
                     metadata: {
-                        ...(options?.metadata ?? {}),
+                        ...(sendOptions.metadata ?? {}),
                         turnId,
                         turnSemantics: 'progress',
                         turnComplete: false,
                     },
                 });
+                return { turnId, durable: true, messageId: result.messageId };
             };
             // Enrich history messages with isOwner
             if (this.agentContext?.ownerId) {

package/dist/index.d.ts

@@ -3,4 +3,4 @@ export { CanonApiError } from '@canonmsg/core';
 export { SessionManager } from './session-manager.js';
 export type { SessionConfig, Session } from './session-manager.js';
 export type { AgentContext, CanonMessage, CanonConversation, SendMessageOptions, CreateConversationOptions, } from '@canonmsg/core';
-export type { SDKMessage, SDKConversation, CanonAgentOptions, MessageHandler, MessageHandlerContext, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';
+export type { SDKMessage, SDKConversation, CanonAgentOptions, MessageHandler, MessageHandlerContext, ProgressMessageOptions, ProgressMessageResult, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';

package/dist/policy-history.d.ts

@@ -0,0 +1,10 @@
+import { type CanonMessage, type ParticipationHistorySnapshot } from '@canonmsg/core';
+export type { ParticipationHistorySnapshot } from '@canonmsg/core';
+/**
+ * Builds message-specific participation history snapshots for backlog delivery.
+ *
+ * `messages` must be ordered newest-first, matching Canon's `getMessages()`
+ * API. Each snapshot is computed from older history only, never from the
+ * target message itself or newer messages that had not occurred yet.
+ */
+export declare function buildParticipationHistorySnapshots(messages: CanonMessage[], agentId: string): Map<string, ParticipationHistorySnapshot>;

package/dist/policy-history.js

@@ -0,0 +1,11 @@
+import { buildParticipationHistorySnapshots as buildSharedParticipationHistorySnapshots, } from '@canonmsg/core';
+/**
+ * Builds message-specific participation history snapshots for backlog delivery.
+ *
+ * `messages` must be ordered newest-first, matching Canon's `getMessages()`
+ * API. Each snapshot is computed from older history only, never from the
+ * target message itself or newer messages that had not occurred yet.
+ */
+export function buildParticipationHistorySnapshots(messages, agentId) {
+    return buildSharedParticipationHistorySnapshots(messages, agentId);
+}

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

@@ -1,17 +1,22 @@
+import { buildParticipationHistorySnapshots } from './policy-history.js';
 import { shouldDispatchInboundMessage } from './turn-filter.js';
 export class PollingManager {
     apiClient;
     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;
@@ -21,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);
     }
@@ -29,10 +35,13 @@ 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 {
-                    const messages = await this.apiClient.getMessages(convo.id, 50);
+                    const page = await this.apiClient.getMessagesPage(convo.id, 50);
+                    const messages = page.messages;
+                    const participationHistory = buildParticipationHistorySnapshots(messages, this.agentId);
                     // Filter to only new messages (after lastSeen, not from self)
                     const lastSeen = this.lastSeenTimestamps.get(convo.id) || 0;
                     const newMessages = messages.filter((m) => {
@@ -41,7 +50,13 @@ export class PollingManager {
                     });
                     const dispatchable = await Promise.all(newMessages.map(async (message) => ({
                         message,
-                        allow: await shouldDispatchInboundMessage(convo.id, this.agentId, message),
+                        allow: await shouldDispatchInboundMessage(convo.id, this.agentId, message, {
+                            conversationType: convo.type,
+                            behavior: page.behavior,
+                            recentHumanCount: participationHistory.get(message.id)?.recentHumanCount,
+                            consecutiveAgentTurns: participationHistory.get(message.id)?.consecutiveAgentTurns,
+                            currentAgentStreakStartedByHuman: participationHistory.get(message.id)?.currentAgentStreakStartedByHuman,
+                        }),
                     })));
                     for (const msg of dispatchable.filter((entry) => entry.allow).map((entry) => entry.message)) {
                         this.debouncer.add(convo.id, msg);
@@ -58,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

@@ -1,4 +1,5 @@
 import { CanonClient, CanonStream } from '@canonmsg/core';
+import { buildParticipationHistorySnapshots } from './policy-history.js';
 import { shouldDispatchInboundMessage } from './turn-filter.js';
 const DISCOVERY_INTERVAL_MS = 5_000;
 /**
@@ -16,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;
@@ -53,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);
@@ -63,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
@@ -88,6 +99,7 @@ export class RealtimeManager {
             this.discoveryTimer = null;
         }
         this.stream.stop();
+        this.onDisconnected?.();
     }
     // ── Conversation discovery ─────────────────────────────────────────
     async discoverNewConversations() {
@@ -108,10 +120,19 @@ export class RealtimeManager {
             // Fetch and deliver pending messages from new conversations
             for (const convoId of newConvoIds) {
                 try {
-                    const messages = await this.apiClient.getMessages(convoId, 50);
+                    const conversation = convos.find((item) => item.id === convoId);
+                    const page = await this.apiClient.getMessagesPage(convoId, 50);
+                    const messages = page.messages;
+                    const participationHistory = buildParticipationHistorySnapshots(messages, this.agentId);
                     const dispatchable = await Promise.all(messages.map(async (message) => ({
                         message,
-                        allow: await shouldDispatchInboundMessage(convoId, this.agentId, message),
+                        allow: await shouldDispatchInboundMessage(convoId, this.agentId, message, {
+                            conversationType: conversation?.type ?? 'unknown',
+                            behavior: page.behavior,
+                            recentHumanCount: participationHistory.get(message.id)?.recentHumanCount,
+                            consecutiveAgentTurns: participationHistory.get(message.id)?.consecutiveAgentTurns,
+                            currentAgentStreakStartedByHuman: participationHistory.get(message.id)?.currentAgentStreakStartedByHuman,
+                        }),
                     })));
                     const newMessages = dispatchable
                         .filter((entry) => entry.allow)

package/dist/turn-filter.d.ts

@@ -1,2 +1,8 @@
-import { type CanonMessage } from '@canonmsg/core';
-export declare function shouldDispatchInboundMessage(conversationId: string, agentId: string, message: CanonMessage): Promise<boolean>;
+import { type ResolvedAgentBehaviorPolicy, type CanonMessage } from '@canonmsg/core';
+export declare function shouldDispatchInboundMessage(conversationId: string, agentId: string, message: CanonMessage, options?: {
+    conversationType?: 'direct' | 'group' | 'unknown';
+    behavior?: ResolvedAgentBehaviorPolicy | null;
+    recentHumanCount?: number;
+    consecutiveAgentTurns?: number;
+    currentAgentStreakStartedByHuman?: boolean;
+}): Promise<boolean>;

package/dist/turn-filter.js

@@ -1,4 +1,4 @@
-import { normalizeTurnState, rtdbRead, shouldTriggerAgentTurn, } from '@canonmsg/core';
+import { evaluateParticipationPolicy, normalizeTurnState, rtdbRead, shouldTriggerAgentTurn, } from '@canonmsg/core';
 function normalizeRuntimeTurnState(value) {
     const turnState = normalizeTurnState(value);
     if (turnState) {
@@ -15,7 +15,7 @@ function normalizeRuntimeTurnState(value) {
     }
     return null;
 }
-export async function shouldDispatchInboundMessage(conversationId, agentId, message) {
+export async function shouldDispatchInboundMessage(conversationId, agentId, message, options) {
     if (message.senderId === agentId)
         return false;
     let senderTurnState = null;
@@ -30,9 +30,22 @@ export async function shouldDispatchInboundMessage(conversationId, agentId, mess
     catch {
         senderTurnState = null;
     }
-    return shouldTriggerAgentTurn({
+    const triggerDecision = shouldTriggerAgentTurn({
         senderType: message.senderType,
         metadata: message.metadata,
         senderTurnState,
+    });
+    if (!triggerDecision.allow)
+        return false;
+    if (!options?.behavior)
+        return true;
+    return evaluateParticipationPolicy(options.behavior, {
+        conversationType: options.conversationType ?? 'unknown',
+        senderType: message.senderType,
+        isOwner: message.isOwner,
+        mentionedAgent: Array.isArray(message.mentions) && message.mentions.includes(agentId),
+        recentHumanCount: options.recentHumanCount,
+        consecutiveAgentTurns: options.consecutiveAgentTurns,
+        currentAgentStreakStartedByHuman: options.currentAgentStreakStartedByHuman,
     }).allow;
 }

package/dist/types.d.ts

@@ -2,6 +2,22 @@ export type { AgentClientType, CanonMessage, CanonConversation, AgentContext, Se
 import type { CanonMessage, CanonConversation, SendMessageOptions } from '@canonmsg/core';
 export type SDKMessage = CanonMessage;
 export type SDKConversation = CanonConversation;
+export interface ProgressMessageOptions extends SendMessageOptions {
+    /**
+     * Persist the progress update to Firestore.
+     * By default, progress stays ephemeral and only updates the live RTDB turn state.
+     */
+    durable?: boolean;
+}
+export type ProgressMessageResult = {
+    turnId: string;
+    durable: false;
+    messageId: null;
+} | {
+    turnId: string;
+    durable: true;
+    messageId: string;
+};
 export interface SessionInfo {
     /** Session ID (= conversationId) */
     id: string;
@@ -30,9 +46,7 @@ export interface MessageHandlerContext {
     replyFinal: (text: string, options?: SendMessageOptions) => Promise<{
         messageId: string;
     }>;
-    replyProgress: (text: string, options?: SendMessageOptions) => Promise<{
-        messageId: string;
-    }>;
+    replyProgress: (text: string, options?: ProgressMessageOptions) => Promise<ProgressMessageResult>;
     /** Soft-delete a message (agent must be the sender) */
     deleteMessage: (messageId: string) => Promise<void>;
     /** Mark conversation as read */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-sdk",
-  "version": "0.3.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.3.0"
+    "@canonmsg/core": "^0.5.0"
   },
   "publishConfig": {
     "access": "public"