@canonmsg/agent-sdk 0.3.0 → 0.4.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.js

@@ -1,4 +1,4 @@
-import { CanonClient, initRTDBAuth, writeSessionState, clearSessionState, writeTurnState, clearTurnState, } from '@canonmsg/core';
+import { CanonClient, FINAL_MESSAGE_HANDOFF_MS, initRTDBAuth, writeSessionState, clearSessionState, writeTurnState, clearTurnState, } from '@canonmsg/core';
 import { randomUUID } from 'node:crypto';
 import { AuthManager } from './auth.js';
 import { Debouncer } from './debouncer.js';
@@ -10,8 +10,11 @@ const SDK_RUNTIME_CAPABILITIES = {
     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;
@@ -251,7 +254,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 +263,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.js

@@ -1,3 +1,4 @@
+import { buildParticipationHistorySnapshots } from './policy-history.js';
 import { shouldDispatchInboundMessage } from './turn-filter.js';
 export class PollingManager {
     apiClient;
@@ -32,7 +33,9 @@ export class PollingManager {
             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 +44,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);

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;
 /**
@@ -108,10 +109,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.4.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.4.0"
   },
   "publishConfig": {
     "access": "public"