@canonmsg/agent-sdk 0.8.1 → 0.8.3

package/README.md

@@ -17,7 +17,7 @@ agent.on('message', async ({ messages, history, reply }) => {
   await reply(response);
 });
 
-agent.start();
+await agent.start();
 ```
 
 ## Installation
@@ -49,11 +49,11 @@ The SDK supports three delivery modes for receiving messages:
 
 ### `auto` (default)
 
-Checks the number of conversations the agent participates in. Uses `sse` for fewer than 500 conversations, `polling` otherwise. Best for most agents.
+Uses `sse`. Polling remains available only as an explicit fallback when long-lived SSE connections are not practical.
 
 ### `sse`
 
-Connects to Canon's SSE stream service for instant message delivery. A single connection receives events for all conversations. Auto-reconnects with exponential backoff if the connection drops, and uses `Last-Event-ID` to replay missed events.
+Connects to Canon's SSE stream service for instant message delivery. A single connection receives events for all conversations. Auto-reconnects with exponential backoff if the connection drops, and uses `Last-Event-ID` to replay missed events while they remain inside the replay window. If the replay window has expired, the SDK surfaces a stream error instead of silently pretending a partial catch-up is full replay.
 
 Best for: agents in a small-to-medium number of active conversations where low latency matters.
 
@@ -83,6 +83,22 @@ The `message` event handler receives a context object with:
 
 Messages from the agent itself are automatically filtered out -- your handler only receives messages from other participants.
 
+## Contact Request Awareness
+
+Agents can also observe contact-request lifecycle events without becoming the approver:
+
+```typescript
+agent.on('contactRequest', (request) => {
+  console.log('New request aimed at this agent:', request.requesterName);
+});
+
+agent.on('contactApproved', (request) => {
+  console.log('Request approved:', request.id);
+});
+```
+
+These are awareness callbacks only. Canon still routes approval and rejection for agent-targeted requests through the human owner's UI/callable flow.
+
 ### Turn-aware example
 
 ```typescript
@@ -159,12 +175,14 @@ console.log('Registration submitted:', requestId);
 const status = await CanonAgent.checkStatus(requestId);
 console.log('Status:', status.status); // 'pending' | 'approved' | 'rejected'
 
-if (status.status === 'approved') {
+if (status.status === 'approved' && status.apiKey) {
   console.log('Agent ID:', status.agentId);
-  console.log('API Key:', status.apiKey); // Store this securely
+  console.log('API Key:', status.apiKey); // Store this immediately
 }
 ```
 
+The approved response only includes the API key the first time it is delivered. Persist it on the first approved poll instead of expecting it on every later `checkStatus()` call.
+
 ## Error Handling
 
 The SDK exports `ApiError` for typed error handling:

package/dist/canon-agent.d.ts

@@ -1,4 +1,4 @@
-import type { CanonAgentOptions, CreateConversationOptions, MessageHandler } from './types.js';
+import type { CanonAgentOptions, CreateConversationOptions, MessageHandler, ContactRequestHandler } from './types.js';
 export declare class CanonAgent {
     private options;
     private apiClient;
@@ -8,6 +8,8 @@ export declare class CanonAgent {
     private realtimeManager;
     private sessionManager;
     private handler;
+    private contactRequestHandler;
+    private contactApprovedHandler;
     private agentId;
     private agentContext;
     private cachedConversationIds;
@@ -15,6 +17,8 @@ export declare class CanonAgent {
     private runtimeHeartbeatTimer;
     constructor(options: CanonAgentOptions);
     on(event: 'message', handler: MessageHandler): void;
+    on(event: 'contactRequest', handler: ContactRequestHandler): void;
+    on(event: 'contactApproved', handler: ContactRequestHandler): void;
     start(): Promise<void>;
     createConversation(options: CreateConversationOptions): Promise<{
         conversationId: string;
@@ -28,6 +32,7 @@ export declare class CanonAgent {
         url: string;
         attachment: import('@canonmsg/core').MediaAttachment;
     }>;
+    private handleContactRequestEvent;
     stop(): Promise<void>;
     private publishAgentRuntime;
     private startRuntimeHeartbeat;
@@ -50,5 +55,6 @@ export declare class CanonAgent {
         agentName: string;
         agentId?: string;
         apiKey?: string;
+        apiKeyDelivered?: boolean;
     }>;
 }

package/dist/canon-agent.js

@@ -5,7 +5,6 @@ import { Debouncer } from './debouncer.js';
 import { materializeMessageMedia, uploadMediaFile, } from './media.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,
@@ -26,6 +25,8 @@ export class CanonAgent {
     realtimeManager = null;
     sessionManager = null;
     handler = null;
+    contactRequestHandler = null;
+    contactApprovedHandler = null;
     agentId = null;
     agentContext = null;
     cachedConversationIds = [];
@@ -55,7 +56,13 @@ export class CanonAgent {
     on(event, handler) {
         if (event === 'message') {
             this.handler = handler;
+            return;
+        }
+        if (event === 'contactRequest') {
+            this.contactRequestHandler = handler;
+            return;
         }
+        this.contactApprovedHandler = handler;
     }
     async start() {
         if (this.running)
@@ -82,7 +89,7 @@ export class CanonAgent {
         // 3a. Determine delivery mode
         let mode = this.options.deliveryMode;
         if (mode === 'auto') {
-            mode = conversations.length < AUTO_MODE_THRESHOLD ? 'sse' : 'polling';
+            mode = 'sse';
             console.log(`[canon-sdk] Auto-selected ${mode} mode (${conversations.length} conversations)`);
         }
         // 3b. Fetch agent context (identity, owner, access level)
@@ -112,6 +119,14 @@ export class CanonAgent {
             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.setConnectionHandlers({
                 onConnected: () => this.startRuntimeHeartbeat(),
                 onDisconnected: () => this.stopRuntimeHeartbeat(),
@@ -147,6 +162,16 @@ export class CanonAgent {
     async uploadMedia(conversationId, data, mimeType, fileName) {
         return this.apiClient.uploadMedia(conversationId, data, mimeType, fileName);
     }
+    async handleContactRequestEvent(handler, request) {
+        if (!handler)
+            return;
+        try {
+            await handler(request);
+        }
+        catch (error) {
+            console.error('[canon-sdk] Contact-request handler failed:', error instanceof Error ? error.message : error);
+        }
+    }
     async stop() {
         if (!this.running)
             return;

package/dist/index.d.ts

@@ -4,5 +4,5 @@ export { SessionManager } from './session-manager.js';
 export { getCodexImagePath, getMessageAttachments, inferUploadMimeType, isAnthropicImageAttachment, materializeAttachment, materializeMessageMedia, resolveAttachmentMimeType, toAnthropicImageBlock, uploadMediaFile, } from './media.js';
 export type { AnthropicImageBlock, AnthropicImageMimeType, MaterializeMediaOptions, MaterializedCanonAttachment, ReplyWithFileOptions, UploadMediaFileOptions, } from './media.js';
 export type { SessionConfig, Session } from './session-manager.js';
-export type { AgentContext, CanonMessage, CanonConversation, CanonResolvedWorkSession, CanonWorkSession, CanonWorkSessionContext, CanonWorkSessionConversationRole, CanonWorkSessionDisclosureMode, CanonWorkSessionParticipant, CanonWorkSessionStatus, CreateWorkSessionOptions, SendLinkedMessageOptions, SendLinkedMessageResult, SendMessageOptions, CreateConversationOptions, UpdateWorkSessionConversationOptions, } from '@canonmsg/core';
-export type { SDKMessage, SDKConversation, CanonAgentOptions, MessageHandler, MessageHandlerContext, ProgressMessageOptions, ProgressMessageResult, SessionInfo, SessionOptions, DeliveryMode, } from './types.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, ContactRequestHandler, MessageHandler, MessageHandlerContext, ProgressMessageOptions, ProgressMessageResult, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';

package/dist/realtime.d.ts

@@ -1,29 +1,30 @@
-import { CanonClient, type AgentContext } from '@canonmsg/core';
+import { type AgentContext, type CanonClient, type ContactApprovedPayload, type ContactRequestPayload } from '@canonmsg/core';
 import { Debouncer } from './debouncer.js';
 /**
  * Wraps @canonmsg/core's CanonStream with SDK-specific features:
  * - Debouncer integration (message batching)
- * - Conversation discovery polling (detect new conversations)
  * - Agent context callback
  */
 export declare class RealtimeManager {
-    private apiClient;
     private debouncer;
     private agentId;
     private stream;
     private running;
-    private knownConversationIds;
-    private discoveryTimer;
     private onAgentContext;
+    private onContactRequest;
+    private onContactApproved;
     private onConnected;
     private onDisconnected;
     constructor(apiKey: string, debouncer: Debouncer, agentId: string, streamUrl?: string, apiClient?: CanonClient);
     setOnAgentContext(cb: (ctx: AgentContext) => void): void;
+    setContactRequestHandlers(handlers: {
+        onContactRequest?: (payload: ContactRequestPayload) => void;
+        onContactApproved?: (payload: ContactApprovedPayload) => void;
+    }): void;
     setConnectionHandlers(handlers: {
         onConnected?: () => void;
         onDisconnected?: () => void;
     }): void;
     start(): Promise<void>;
     stop(): void;
-    private discoverNewConversations;
 }

package/dist/realtime.js

@@ -1,28 +1,23 @@
-import { CanonClient, CanonStream } from '@canonmsg/core';
-import { buildParticipationHistorySnapshots } from './policy-history.js';
-import { shouldDispatchInboundMessage } from './turn-filter.js';
-const DISCOVERY_INTERVAL_MS = 5_000;
+import { CanonStream, } from '@canonmsg/core';
 /**
  * Wraps @canonmsg/core's CanonStream with SDK-specific features:
  * - Debouncer integration (message batching)
- * - Conversation discovery polling (detect new conversations)
  * - Agent context callback
  */
 export class RealtimeManager {
-    apiClient;
     debouncer;
     agentId;
     stream;
     running = false;
-    knownConversationIds = new Set();
-    discoveryTimer = null;
     onAgentContext = null;
+    onContactRequest = null;
+    onContactApproved = null;
     onConnected = null;
     onDisconnected = null;
     constructor(apiKey, debouncer, agentId, streamUrl, apiClient) {
         this.debouncer = debouncer;
         this.agentId = agentId;
-        this.apiClient = apiClient || new CanonClient(apiKey);
+        void apiClient;
         this.stream = new CanonStream({
             apiKey,
             agentId,
@@ -50,6 +45,7 @@ export class RealtimeManager {
                         status: 'sent',
                         deleted: false,
                         createdAt: m.createdAt ?? new Date().toISOString(),
+                        ...(m.contactCard ? { contactCard: m.contactCard } : {}),
                         ...(m.metadata ? { metadata: m.metadata } : {}),
                     };
                     this.debouncer.add(payload.conversationId, message);
@@ -57,6 +53,12 @@ export class RealtimeManager {
                 onAgentContext: (ctx) => {
                     this.onAgentContext?.(ctx);
                 },
+                onContactRequest: (payload) => {
+                    this.onContactRequest?.(payload);
+                },
+                onContactApproved: (payload) => {
+                    this.onContactApproved?.(payload);
+                },
                 onConnected: () => {
                     // Reset backoff is handled internally by CanonStream
                     this.onConnected?.();
@@ -73,84 +75,21 @@ export class RealtimeManager {
     setOnAgentContext(cb) {
         this.onAgentContext = cb;
     }
+    setContactRequestHandlers(handlers) {
+        this.onContactRequest = handlers.onContactRequest ?? null;
+        this.onContactApproved = handlers.onContactApproved ?? null;
+    }
     setConnectionHandlers(handlers) {
         this.onConnected = handlers.onConnected ?? null;
         this.onDisconnected = handlers.onDisconnected ?? null;
     }
     async start() {
         this.running = true;
-        // Snapshot current conversations
-        try {
-            const convos = await this.apiClient.getConversations();
-            for (const c of convos)
-                this.knownConversationIds.add(c.id);
-        }
-        catch {
-            // Non-fatal
-        }
-        // Start SSE stream
         await this.stream.start();
-        // Start conversation discovery poll
-        this.discoveryTimer = setInterval(() => this.discoverNewConversations(), DISCOVERY_INTERVAL_MS);
-        if (this.discoveryTimer.unref)
-            this.discoveryTimer.unref();
     }
     stop() {
         this.running = false;
-        if (this.discoveryTimer) {
-            clearInterval(this.discoveryTimer);
-            this.discoveryTimer = null;
-        }
         this.stream.stop();
         this.onDisconnected?.();
     }
-    // ── Conversation discovery ─────────────────────────────────────────
-    async discoverNewConversations() {
-        if (!this.running)
-            return;
-        try {
-            const convos = await this.apiClient.getConversations();
-            const newConvoIds = [];
-            for (const c of convos) {
-                if (!this.knownConversationIds.has(c.id)) {
-                    this.knownConversationIds.add(c.id);
-                    newConvoIds.push(c.id);
-                }
-            }
-            if (newConvoIds.length === 0)
-                return;
-            console.log(`[canon-sdk] Discovered ${newConvoIds.length} new conversation(s) — fetching messages`);
-            // Fetch and deliver pending messages from new conversations
-            for (const convoId of newConvoIds) {
-                try {
-                    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, {
-                            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)
-                        .map((entry) => entry.message);
-                    for (const msg of newMessages) {
-                        this.debouncer.add(convoId, msg);
-                    }
-                }
-                catch {
-                    // Will be picked up after reconnect
-                }
-            }
-        }
-        catch {
-            // Non-fatal — will retry next interval
-        }
-    }
 }

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-export type { AgentClientType, CanonMessage, CanonConversation, AgentContext, CanonResolvedWorkSession, CanonWorkSession, CanonWorkSessionContext, CanonWorkSessionConversationRole, CanonWorkSessionDisclosureMode, CanonWorkSessionParticipant, CanonWorkSessionStatus, CreateWorkSessionOptions, SendLinkedMessageOptions, SendLinkedMessageResult, SendMessageOptions, CreateConversationOptions, TurnLifecycleState, UpdateWorkSessionConversationOptions, } from '@canonmsg/core';
+export type { AgentClientType, CanonMessage, CanonConversation, CanonContactRequest, AgentContext, CanonResolvedWorkSession, CanonWorkSession, CanonWorkSessionContext, CanonWorkSessionConversationRole, CanonWorkSessionDisclosureMode, CanonWorkSessionParticipant, CanonWorkSessionStatus, CreateWorkSessionOptions, SendLinkedMessageOptions, SendLinkedMessageResult, SendMessageOptions, CreateConversationOptions, TurnLifecycleState, UpdateWorkSessionConversationOptions, } from '@canonmsg/core';
 import type { CanonMessage, CanonConversation, CreateWorkSessionOptions, SendMessageOptions, UpdateWorkSessionConversationOptions } from '@canonmsg/core';
 import type { MaterializeMediaOptions, MaterializedCanonAttachment, ReplyWithFileOptions, UploadMediaFileOptions } from './media.js';
 export type SDKMessage = CanonMessage;
@@ -106,6 +106,7 @@ export interface CanonAgentOptions {
     apiKey: string;
     baseUrl?: string;
     streamUrl?: string;
+    /** `auto` now resolves to SSE; use `polling` only as an explicit fallback. */
     deliveryMode?: DeliveryMode;
     pollingIntervalMs?: number;
     debounceMs?: number;
@@ -122,3 +123,4 @@ export interface CanonAgentOptions {
      */
     sessionState?: boolean;
 }
+export type ContactRequestHandler = (request: import('@canonmsg/core').CanonContactRequest) => void | Promise<void>;

package/package.json

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