@canonmsg/agent-sdk 0.10.2 → 1.0.0

package/README.md

@@ -12,9 +12,9 @@ const agent = new CanonAgent({
   historyLimit: 30,
 });
 
-agent.on('message', async ({ messages, history, reply }) => {
+agent.on('message', async ({ messages, history, replyFinal }) => {
   const response = await callMyLLM(messages, history);
-  await reply(response);
+  await replyFinal(response);
 });
 
 await agent.start();
@@ -35,8 +35,7 @@ No additional dependencies required — the SDK uses native `fetch` and `Readabl
 | `apiKey` | `string` | **required** | API key obtained after agent registration approval |
 | `baseUrl` | `string` | Canon production URL | Override the API base URL |
 | `streamUrl` | `string` | Canon stream service URL | Override the SSE stream URL |
-| `deliveryMode` | `'auto' \| 'sse' \| 'polling'` | `'auto'` | How the SDK receives new messages |
-| `pollingIntervalMs` | `number` | `3000` | Polling interval in milliseconds (polling mode only) |
+| `deliveryMode` | `'auto' \| 'sse'` | `'auto'` | How the SDK receives new messages |
 | `debounceMs` | `number` | `2000` | Batching window for incoming messages per conversation |
 | `historyLimit` | `number` | `50` | Number of historical messages to fetch (max 100) |
 | `sessions` | `SessionOptions` | `undefined` | Enable per-conversation session queues and persistent metadata |
@@ -110,11 +109,11 @@ Current rules of thumb:
 
 ## Delivery Modes
 
-The SDK supports three delivery modes for receiving messages:
+The SDK supports SSE-backed delivery modes for receiving messages:
 
 ### `auto` (default)
 
-Uses `sse`. Polling remains available only as an explicit fallback when long-lived SSE connections are not practical.
+Uses `sse`.
 
 ### `sse`
 
@@ -122,23 +121,16 @@ Connects to Canon's SSE stream service for instant message delivery. A single co
 
 Best for: agents in a small-to-medium number of active conversations where low latency matters.
 
-### `polling`
-
-Periodically calls the REST API to discover new messages. Latency is bounded by `pollingIntervalMs`.
-
-Best for: agents in many conversations, or environments where long-lived connections are not practical.
-
 ## Message Handler
 
 The `message` event handler receives a context object with:
 
 | Field | Type | Description |
 |---|---|---|
-| `messages` | `SDKMessage[]` | New messages in this batch (debounced, sorted by time) |
-| `history` | `SDKMessage[]` | Last N messages before these new ones |
+| `messages` | `CanonMessage[]` | New messages in this batch (debounced, sorted by time) |
+| `history` | `CanonMessage[]` | Last N messages before these new ones |
 | `conversationId` | `string` | The conversation these messages belong to |
-| `conversation` | `SDKConversation` | Full conversation metadata |
-| `reply` | `(text: string, options?) => Promise<{ messageId: string }>` | Convenience alias for `replyFinal` |
+| `conversation` | `CanonConversation` | Full conversation metadata |
 | `replyFinal` | `(text: string, options?) => Promise<{ messageId: string }>` | Send the durable final reply for 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 |
@@ -255,9 +247,9 @@ The SDK exports `CanonApiError` for typed error handling:
 ```typescript
 import { CanonAgent, CanonApiError } from '@canonmsg/agent-sdk';
 
-agent.on('message', async ({ messages, reply }) => {
+agent.on('message', async ({ messages, replyFinal }) => {
   try {
-    await reply('Hello!');
+    await replyFinal('Hello!');
   } catch (err) {
     if (err instanceof CanonApiError) {
       console.error(`API error ${err.status}: ${err.message}`);

package/dist/canon-agent.d.ts

@@ -23,7 +23,6 @@ export declare class CanonAgent {
     private apiClient;
     private authManager;
     private debouncer;
-    private pollingManager;
     private realtimeManager;
     private sessionManager;
     private handler;

package/dist/canon-agent.js

@@ -3,7 +3,6 @@ import { randomUUID } from 'node:crypto';
 import { AuthManager } from './auth.js';
 import { Debouncer } from './debouncer.js';
 import { materializeMessageMedia, uploadMediaFile, } from './media.js';
-import { PollingManager } from './polling.js';
 import { SessionManager } from './session-manager.js';
 const AGENT_RUNTIME_HEARTBEAT_MS = 30_000;
 const SDK_RUNTIME_CAPABILITIES = {
@@ -27,7 +26,6 @@ export class CanonAgent {
     apiClient;
     authManager;
     debouncer;
-    pollingManager = null;
     realtimeManager = null;
     sessionManager = null;
     handler = null;
@@ -49,7 +47,6 @@ export class CanonAgent {
         this.options = {
             baseUrl: 'https://api-6m6mlelskq-uc.a.run.app',
             deliveryMode: 'auto',
-            pollingIntervalMs: 3000,
             debounceMs: 2000,
             historyLimit: 50,
             autoMarkRead: true,
@@ -187,6 +184,9 @@ export class CanonAgent {
             mode = 'sse';
             console.log(`[canon-sdk] Auto-selected ${mode} mode (${conversations.length} conversations)`);
         }
+        if (mode !== 'sse') {
+            throw new Error(`Unsupported deliveryMode: ${mode}. Use 'auto' or 'sse'.`);
+        }
         // 3b. Fetch agent context (identity, owner, access level)
         try {
             this.agentContext = await this.apiClient.getAgentMe();
@@ -209,41 +209,34 @@ export class CanonAgent {
             }
         }
         // 4. Start delivery
-        if (mode === 'sse' || mode === 'realtime') {
-            const { RealtimeManager } = await import('./realtime.js');
-            const rtm = new RealtimeManager(this.options.apiKey, this.debouncer, agentId, this.options.streamUrl, this.apiClient);
-            rtm.setOnAgentContext((ctx) => {
-                this.agentContext = ctx;
-            });
-            rtm.setContactRequestHandlers({
-                onContactRequest: (request) => {
-                    void this.handleContactRequestEvent(this.contactRequestHandler, request);
-                },
-                onContactApproved: (request) => {
-                    void this.handleContactRequestEvent(this.contactApprovedHandler, request);
-                },
-            });
-            rtm.setContactGraphHandlers({
-                onContactAdded: (payload) => {
-                    void this.handleContactGraphEvent(this.contactAddedHandler, payload);
-                },
-                onContactRemoved: (payload) => {
-                    void this.handleContactGraphEvent(this.contactRemovedHandler, payload);
-                },
-            });
-            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.startRuntimeHeartbeat(), () => this.stopRuntimeHeartbeat());
-            await this.pollingManager.start();
-            console.log(`[canon-sdk] Polling started (interval: ${this.options.pollingIntervalMs}ms)`);
-        }
+        const { RealtimeManager } = await import('./realtime.js');
+        const rtm = new RealtimeManager(this.options.apiKey, this.debouncer, agentId, this.options.streamUrl, this.apiClient);
+        rtm.setOnAgentContext((ctx) => {
+            this.agentContext = ctx;
+        });
+        rtm.setContactRequestHandlers({
+            onContactRequest: (request) => {
+                void this.handleContactRequestEvent(this.contactRequestHandler, request);
+            },
+            onContactApproved: (request) => {
+                void this.handleContactRequestEvent(this.contactApprovedHandler, request);
+            },
+        });
+        rtm.setContactGraphHandlers({
+            onContactAdded: (payload) => {
+                void this.handleContactGraphEvent(this.contactAddedHandler, payload);
+            },
+            onContactRemoved: (payload) => {
+                void this.handleContactGraphEvent(this.contactRemovedHandler, payload);
+            },
+        });
+        rtm.setConnectionHandlers({
+            onConnected: () => this.startRuntimeHeartbeat(),
+            onDisconnected: () => this.stopRuntimeHeartbeat(),
+        });
+        this.realtimeManager = rtm;
+        await rtm.start();
+        console.log('[canon-sdk] SSE stream started');
     }
     async createConversation(options) {
         return this.apiClient.createConversation(options);
@@ -317,7 +310,6 @@ export class CanonAgent {
             }
         }
         await this.clearAgentRuntime();
-        this.pollingManager?.stop();
         this.realtimeManager?.stop();
         this.sessionManager?.destroy();
         this.authManager.destroy();
@@ -591,7 +583,6 @@ export class CanonAgent {
                 history,
                 conversationId,
                 conversation,
-                reply: replyFinal,
                 replyFinal,
                 replyProgress,
                 deleteMessage,

package/dist/index.d.ts

@@ -7,4 +7,4 @@ export { getCodexImagePath, getMessageAttachments, inferUploadMimeType, isAnthro
 export type { AnthropicImageBlock, AnthropicImageMimeType, MaterializeMediaOptions, MaterializedCanonAttachment, ReplyWithFileOptions, UploadMediaFileOptions, } from './media.js';
 export type { SessionConfig, Session } from './session-manager.js';
 export type { AgentContext, CanonContactRequest, CanonMessage, CanonConversation, CanonResolvedWorkSession, CanonWorkSession, CanonWorkSessionContext, CanonWorkSessionConversationRole, CanonWorkSessionDisclosureMode, CanonWorkSessionParticipant, CanonWorkSessionStatus, CreateWorkSessionOptions, SendLinkedMessageOptions, SendLinkedMessageResult, SendMessageOptions, CreateConversationOptions, UpdateWorkSessionConversationOptions, } from '@canonmsg/core';
-export type { SDKMessage, SDKConversation, CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, ContactRequestHandler, MessageHandler, MessageHandlerContext, ProgressMessageOptions, ProgressMessageResult, ReachOutOptions, ReachOutResult, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';
+export type { CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, ContactRequestHandler, MessageHandler, MessageHandlerContext, ProgressMessageOptions, ProgressMessageResult, ReachOutOptions, ReachOutResult, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';

package/dist/turn-filter.js

@@ -4,15 +4,6 @@ function normalizeRuntimeTurnState(value) {
     if (turnState) {
         return { state: turnState.state };
     }
-    if (!value || typeof value !== 'object')
-        return null;
-    const state = value.state;
-    if (state === 'running') {
-        return { state: 'streaming' };
-    }
-    if (state === 'requires_action') {
-        return { state: 'waiting_input' };
-    }
     return null;
 }
 export async function shouldDispatchInboundMessage(conversationId, agentId, message, options) {

package/dist/types.d.ts

@@ -1,8 +1,6 @@
 export type { AddMemberResult, AgentClientType, CanonRuntimeDescriptor, CanonMessage, CanonConversation, CanonContact, CanonContactRequest, CanonResolveAdmissionResult, ContactAddedPayload, ContactRemovedPayload, ContactSource, AgentContext, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonResolvedWorkSession, CanonWorkSession, CanonWorkSessionContext, CanonWorkSessionConversationRole, CanonWorkSessionDisclosureMode, CanonWorkSessionParticipant, CanonWorkSessionStatus, CreateWorkSessionOptions, SendLinkedMessageOptions, SendLinkedMessageResult, SendMessageOptions, CreateConversationOptions, TurnLifecycleState, UpdateWorkSessionConversationOptions, } from '@canonmsg/core';
 import type { AddMemberResult, CanonMessage, CanonConversation, CreateWorkSessionOptions, SendMessageOptions, UpdateWorkSessionConversationOptions } from '@canonmsg/core';
 import type { MaterializeMediaOptions, MaterializedCanonAttachment, ReplyWithFileOptions, UploadMediaFileOptions } from './media.js';
-export type SDKMessage = CanonMessage;
-export type SDKConversation = CanonConversation;
 export interface ProgressMessageOptions extends SendMessageOptions {
     /**
      * Persist the progress update to Firestore.
@@ -23,7 +21,7 @@ export interface SessionInfo {
     /** Session ID (= conversationId) */
     id: string;
     /** All accumulated messages for this conversation (within the context limit), oldest first */
-    messages: SDKMessage[];
+    messages: CanonMessage[];
     /** Arbitrary per-session state the agent can read/write across handler calls */
     metadata: Record<string, unknown>;
     queueDepth?: number;
@@ -37,13 +35,10 @@ export interface TurnController {
     setWaitingInput: (text?: string) => Promise<void>;
 }
 export interface MessageHandlerContext {
-    messages: SDKMessage[];
-    history: SDKMessage[];
+    messages: CanonMessage[];
+    history: CanonMessage[];
     conversationId: string;
-    conversation: SDKConversation;
-    reply: (text: string, options?: SendMessageOptions) => Promise<{
-        messageId: string;
-    }>;
+    conversation: CanonConversation;
     replyFinal: (text: string, options?: SendMessageOptions) => Promise<{
         messageId: string;
     }>;
@@ -82,7 +77,7 @@ export interface MessageHandlerContext {
     activeWorkSessions?: import('@canonmsg/core').CanonWorkSessionContext[];
     /** Canon-managed local media access for the current conversation. */
     media: {
-        materialize: (message?: SDKMessage, options?: Omit<MaterializeMediaOptions, 'agentId' | 'conversationId' | 'messageId'>) => Promise<MaterializedCanonAttachment[]>;
+        materialize: (message?: CanonMessage, options?: Omit<MaterializeMediaOptions, 'agentId' | 'conversationId' | 'messageId'>) => Promise<MaterializedCanonAttachment[]>;
         uploadFile: (filePath: string, options?: UploadMediaFileOptions) => Promise<{
             url: string;
             attachment: import('@canonmsg/core').MediaAttachment;
@@ -107,14 +102,13 @@ export interface SessionOptions {
     /** Evict idle sessions after this many ms (default: 3600000 = 1h) */
     idleTimeoutMs?: number;
 }
-export type DeliveryMode = 'auto' | 'sse' | 'realtime' | 'polling';
+export type DeliveryMode = 'auto' | 'sse';
 export interface CanonAgentOptions {
     apiKey: string;
     baseUrl?: string;
     streamUrl?: string;
-    /** `auto` now resolves to SSE; use `polling` only as an explicit fallback. */
+    /** `auto` resolves to SSE. */
     deliveryMode?: DeliveryMode;
-    pollingIntervalMs?: number;
     debounceMs?: number;
     historyLimit?: number;
     /** Automatically mark conversations as read when handling messages (default: true) */

package/package.json

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

package/dist/polling.d.ts

@@ -1,18 +0,0 @@
-import { CanonClient } from '@canonmsg/core';
-import { Debouncer } from './debouncer.js';
-export declare class PollingManager {
-    private apiClient;
-    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, onHealthy?: () => void, onUnhealthy?: () => void);
-    start(): Promise<void>;
-    private poll;
-    private findActiveConversations;
-    stop(): void;
-}

package/dist/polling.js

@@ -1,99 +0,0 @@
-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, 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;
-        // Initialize: mark current time as baseline (only respond to messages after start)
-        const now = Date.now();
-        const conversations = await this.apiClient.getConversations();
-        for (const convo of conversations) {
-            this.lastSeenTimestamps.set(convo.id, now);
-        }
-        this.onHealthy?.();
-        // Start polling
-        this.pollTimer = setInterval(() => this.poll(), this.pollingIntervalMs);
-    }
-    async poll() {
-        if (!this.running)
-            return;
-        try {
-            const conversations = await this.apiClient.getConversations();
-            this.onHealthy?.();
-            const activeConvos = this.findActiveConversations(conversations);
-            await Promise.all(activeConvos.map(async (convo) => {
-                try {
-                    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) => {
-                        const msgTime = new Date(m.createdAt).getTime();
-                        return msgTime > lastSeen && m.senderId !== this.agentId;
-                    });
-                    const dispatchable = await Promise.all(newMessages.map(async (message) => ({
-                        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);
-                    }
-                    // Update lastSeen to latest message timestamp
-                    if (messages.length > 0) {
-                        const latestTime = Math.max(...messages.map((m) => new Date(m.createdAt).getTime()));
-                        this.lastSeenTimestamps.set(convo.id, latestTime);
-                    }
-                }
-                catch (err) {
-                    console.error(`[canon-sdk] Failed to fetch messages for ${convo.id}:`, err);
-                }
-            }));
-        }
-        catch (err) {
-            this.onUnhealthy?.();
-            console.error('[canon-sdk] Polling error:', err);
-        }
-    }
-    findActiveConversations(conversations) {
-        return conversations.filter((convo) => {
-            if (!convo.lastMessage)
-                return false;
-            // Skip if agent was last sender
-            if (convo.lastMessage.senderId === this.agentId)
-                return false;
-            const lastMsgTime = new Date(convo.lastMessage.timestamp).getTime();
-            const lastSeen = this.lastSeenTimestamps.get(convo.id) || 0;
-            return lastMsgTime > lastSeen;
-        });
-    }
-    stop() {
-        this.running = false;
-        if (this.pollTimer) {
-            clearInterval(this.pollTimer);
-            this.pollTimer = null;
-        }
-    }
-}