@canonmsg/agent-sdk 1.2.0 → 1.3.0

package/README.md

@@ -243,7 +243,7 @@ Register a new agent using the static helpers (no API key needed):
 import { CanonAgent } from '@canonmsg/agent-sdk';
 
 // 1. Submit registration request
-const { requestId } = await CanonAgent.register({
+const { requestId, pollToken } = await CanonAgent.register({
   name: 'My Agent',
   description: 'A helpful assistant',
   ownerPhone: '+1234567890',
@@ -251,18 +251,20 @@ const { requestId } = await CanonAgent.register({
 });
 
 console.log('Registration submitted:', requestId);
+console.log('Poll token:', pollToken);
 
 // 2. Poll for approval
-const status = await CanonAgent.checkStatus(requestId);
+const status = await CanonAgent.checkStatus(requestId, { pollToken });
 console.log('Status:', status.status); // 'pending' | 'approved' | 'rejected'
 
 if (status.status === 'approved' && status.apiKey) {
   console.log('Agent ID:', status.agentId);
   console.log('API Key:', status.apiKey); // Store this immediately
+  await CanonAgent.ackStatus(requestId, { pollToken });
 }
 ```
 
-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.
+The approved response only includes the API key until you acknowledge delivery. Persist it on the first approved poll, then call `ackStatus()` so Canon clears the plaintext key from the request.
 
 ## Error Handling
 

package/dist/canon-agent.d.ts

@@ -46,6 +46,8 @@ export declare class CanonAgent {
     private runtimeControlPollTimer;
     private readonly lastSeenSignal;
     private readonly activeAbortControllers;
+    private readonly conversationMemberIds;
+    private readonly pendingMembershipChanges;
     constructor(options: CanonAgentOptions);
     on(event: 'message', handler: MessageHandler): void;
     on(event: 'contactRequest', handler: ContactRequestHandler): void;
@@ -105,6 +107,9 @@ export declare class CanonAgent {
     private stopRuntimeHeartbeat;
     private clearAgentRuntime;
     private rememberConversationId;
+    private rememberConversationMembers;
+    private handleConversationUpdated;
+    private buildGroupContext;
     private baselineRuntimeControlSignals;
     private startRuntimeControlPolling;
     private stopRuntimeControlPolling;
@@ -125,12 +130,20 @@ export declare class CanonAgent {
         baseUrl?: string;
     }): Promise<{
         requestId: string;
+        pollToken?: string;
     }>;
-    static checkStatus(requestId: string, baseUrl?: string): Promise<{
+    static checkStatus(requestId: string, options?: string | {
+        baseUrl?: string;
+        pollToken?: string;
+    }): Promise<{
         status: string;
         agentName: string;
         agentId?: string;
         apiKey?: string;
         apiKeyDelivered?: boolean;
     }>;
+    static ackStatus(requestId: string, options?: string | {
+        baseUrl?: string;
+        pollToken?: string;
+    }): Promise<void>;
 }

package/dist/canon-agent.js

@@ -1,4 +1,4 @@
-import { CanonClient, createRuntimeStatePublisher, FINAL_MESSAGE_HANDOFF_MS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, initRTDBAuth, rtdbRead, rtdbWrite, normalizeTurnMetadata, reachOutToCanonContact, } from '@canonmsg/core';
+import { CanonClient, buildCanonGroupContext, createRuntimeStatePublisher, diffCanonMemberIds, FINAL_MESSAGE_HANDOFF_MS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, initRTDBAuth, rtdbRead, rtdbWrite, normalizeTurnMetadata, reachOutToCanonContact, resolveMessageActiveSelfContextId, selectActiveSelfContexts, } from '@canonmsg/core';
 import { randomUUID } from 'node:crypto';
 import { AuthManager } from './auth.js';
 import { Debouncer } from './debouncer.js';
@@ -49,6 +49,8 @@ export class CanonAgent {
     runtimeControlPollTimer = null;
     lastSeenSignal = new Map();
     activeAbortControllers = new Map();
+    conversationMemberIds = new Map();
+    pendingMembershipChanges = new Map();
     constructor(options) {
         this.options = {
             baseUrl: 'https://api-6m6mlelskq-uc.a.run.app',
@@ -178,6 +180,7 @@ export class CanonAgent {
                     status: 'messaged',
                     conversationId: result.conversationId,
                     messageId: result.messageId,
+                    selfContextId: result.selfContextId,
                 }
                 : result;
         }
@@ -207,6 +210,7 @@ export class CanonAgent {
         try {
             conversations = await this.apiClient.getConversations();
             this.cachedConversationIds = conversations.map((c) => c.id);
+            this.rememberConversationMembers(conversations);
         }
         catch {
             // Non-fatal — delivery mode will fall back to default
@@ -265,6 +269,9 @@ export class CanonAgent {
                 void this.handleContactGraphEvent(this.contactRemovedHandler, payload);
             },
         });
+        rtm.setConversationUpdatedHandler((payload) => {
+            this.handleConversationUpdated(payload);
+        });
         rtm.setConnectionHandlers({
             onConnected: () => this.startRuntimeHeartbeat(),
             onDisconnected: () => this.stopRuntimeHeartbeat(),
@@ -437,6 +444,41 @@ export class CanonAgent {
             return;
         this.cachedConversationIds.push(conversationId);
     }
+    rememberConversationMembers(conversations) {
+        for (const conversation of conversations) {
+            this.conversationMemberIds.set(conversation.id, [...(conversation.memberIds ?? [])]);
+        }
+    }
+    handleConversationUpdated(payload) {
+        const rawMemberIds = payload.changes.memberIds;
+        if (!Array.isArray(rawMemberIds))
+            return;
+        const memberIds = rawMemberIds.filter((id) => typeof id === 'string');
+        const hadPreviousMemberIds = this.conversationMemberIds.has(payload.conversationId);
+        const previousMemberIds = this.conversationMemberIds.get(payload.conversationId) ?? [];
+        const membershipChange = payload.membershipChange
+            ?? (hadPreviousMemberIds ? diffCanonMemberIds(previousMemberIds, memberIds) : null);
+        this.conversationMemberIds.set(payload.conversationId, memberIds);
+        if (membershipChange) {
+            this.pendingMembershipChanges.set(payload.conversationId, membershipChange);
+        }
+        if (this.agentId && !memberIds.includes(this.agentId)) {
+            this.cachedConversationIds = this.cachedConversationIds.filter((id) => id !== payload.conversationId);
+        }
+        else {
+            this.rememberConversationId(payload.conversationId);
+        }
+    }
+    buildGroupContext(input) {
+        return buildCanonGroupContext({
+            conversation: input.conversation,
+            messages: [...input.history, ...input.messages],
+            agentId: input.agent.agentId,
+            ownerId: input.agent.ownerId,
+            ownerName: input.agent.ownerName,
+            membershipChange: input.membershipChange,
+        });
+    }
     async baselineRuntimeControlSignals(conversationIds) {
         if (!this.agentId || !this.hasRuntimeSignalSupport())
             return;
@@ -655,6 +697,7 @@ export class CanonAgent {
             }
             // Get conversation info
             const conversations = await this.apiClient.getConversations();
+            this.rememberConversationMembers(conversations);
             const conversation = conversations.find((c) => c.id === conversationId);
             if (!conversation)
                 return;
@@ -664,13 +707,11 @@ export class CanonAgent {
                     await this.apiClient.setTyping(conversationId, true, 'typing');
                 }
                 catch { }
+                const sendOptions = withActiveSelfContext(options);
                 const result = await this.apiClient.sendMessage(conversationId, text, {
-                    ...(options ?? {}),
-                    ...(options?.selfContextId === undefined && activeSelfContextId
-                        ? { selfContextId: activeSelfContextId }
-                        : {}),
+                    ...sendOptions,
                     metadata: {
-                        ...(options?.metadata ?? {}),
+                        ...(sendOptions.metadata ?? {}),
                         turnId,
                         turnSemantics: 'turn_complete',
                         turnComplete: true,
@@ -689,10 +730,11 @@ export class CanonAgent {
                     return { turnId, durable: false, messageId: null };
                 }
                 const { durable: _durable, ...sendOptions } = options;
+                const sendOptionsWithContext = withActiveSelfContext(sendOptions);
                 const result = await this.apiClient.sendMessage(conversationId, text, {
-                    ...sendOptions,
+                    ...sendOptionsWithContext,
                     metadata: {
-                        ...(sendOptions.metadata ?? {}),
+                        ...(sendOptionsWithContext.metadata ?? {}),
                         turnId,
                         turnSemantics: 'progress',
                         turnComplete: false,
@@ -707,8 +749,19 @@ export class CanonAgent {
                     m.isOwner = m.senderId === ownerId;
                 }
             }
-            const selfContexts = page.selfContexts ?? [];
-            const activeSelfContextId = selfContexts[0]?.id;
+            const latestMessage = hydratedMessages[hydratedMessages.length - 1] ?? null;
+            const resolvedActiveSelfContextId = resolveMessageActiveSelfContextId({
+                messageId: latestMessage?.id,
+                activeSelfContextIdByMessageId: page.activeSelfContextIdByMessageId,
+            });
+            const selfContexts = selectActiveSelfContexts(page.selfContexts, resolvedActiveSelfContextId);
+            const activeSelfContextId = selfContexts.length > 0 ? resolvedActiveSelfContextId : null;
+            const withActiveSelfContext = (options) => {
+                const base = { ...(options ?? {}) };
+                if (base.selfContextId !== undefined)
+                    return base;
+                return activeSelfContextId ? { ...base, selfContextId: activeSelfContextId } : base;
+            };
             // Build agent context (fallback to minimal if not yet received)
             const agent = this.agentContext ?? {
                 agentId: this.agentId,
@@ -718,6 +771,15 @@ export class CanonAgent {
                 inboundPolicy: 'approval-required',
                 groupJoinPolicy: 'approval-required',
             };
+            const membershipChange = this.pendingMembershipChanges.get(conversationId) ?? null;
+            this.pendingMembershipChanges.delete(conversationId);
+            const groupContext = this.buildGroupContext({
+                conversation,
+                history,
+                messages: hydratedMessages,
+                agent,
+                membershipChange,
+            });
             // Build context methods bound to this conversation
             const deleteMessage = (messageId) => this.apiClient.deleteMessage(conversationId, messageId);
             const markAsRead = () => this.apiClient.markAsRead(conversationId);
@@ -740,6 +802,10 @@ export class CanonAgent {
                     },
                 },
             });
+            const reachOut = (card, options) => this.reachOut(card, {
+                ...(options ?? {}),
+                sourceConversationId: conversationId,
+            });
             const uploadFile = (filePath, options) => uploadMediaFile(this.apiClient, conversationId, filePath, options);
             const replyWithFile = async (filePath, text = '', options) => {
                 try {
@@ -753,9 +819,9 @@ export class CanonAgent {
                             ? { replyToPosition: options.replyToPosition }
                             : {}),
                         ...(options?.mentions ? { mentions: options.mentions } : {}),
-                        ...(options?.selfContextId === undefined && activeSelfContextId
-                            ? { selfContextId: activeSelfContextId }
-                            : {}),
+                        ...withActiveSelfContext(options?.selfContextId !== undefined
+                            ? { selfContextId: options.selfContextId }
+                            : undefined),
                         metadata: {
                             ...(options?.metadata ?? {}),
                             turnId,
@@ -782,6 +848,7 @@ export class CanonAgent {
                 history,
                 conversationId,
                 conversation,
+                ...(groupContext ? { groupContext } : {}),
                 replyFinal,
                 replyProgress,
                 deleteMessage,
@@ -791,7 +858,9 @@ export class CanonAgent {
                 addMember,
                 removeMember,
                 sendContextualMessage,
+                reachOut,
                 agent,
+                activeSelfContextId,
                 selfContexts,
                 abortSignal: abortController.signal,
                 media: {
@@ -892,7 +961,14 @@ export class CanonAgent {
         const { baseUrl, ...body } = options;
         return CanonClient.register(baseUrl, body);
     }
-    static async checkStatus(requestId, baseUrl) {
-        return CanonClient.checkStatus(baseUrl, requestId);
+    static async checkStatus(requestId, options) {
+        const baseUrl = typeof options === 'string' ? options : options?.baseUrl;
+        const pollToken = typeof options === 'string' ? undefined : options?.pollToken;
+        return CanonClient.checkStatus(baseUrl, requestId, pollToken);
+    }
+    static async ackStatus(requestId, options) {
+        const baseUrl = typeof options === 'string' ? options : options?.baseUrl;
+        const pollToken = typeof options === 'string' ? undefined : options?.pollToken;
+        await CanonClient.ackRegistrationStatus(baseUrl, requestId, pollToken);
     }
 }

package/dist/index.d.ts

@@ -6,5 +6,5 @@ export { SessionManager } from './session-manager.js';
 export { DEFAULT_MEDIA_CACHE_DIR, getCodexImagePath, getMessageAttachments, inferUploadMimeType, isAnthropicImageAttachment, materializeAttachment, materializeMessageMedia, resolveAttachmentMimeType, sendMediaFileMessage, 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, CanonContactRequest, CanonMessage, CanonConversation, CanonSelfContext, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, CreateConversationOptions, } from '@canonmsg/core';
+export type { AgentContext, CanonGroupContext, CanonKnownRecentParticipant, CanonMembershipChange, CanonContactRequest, CanonMessage, CanonConversation, CanonSelfContext, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, CreateConversationOptions, } from '@canonmsg/core';
 export type { CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, ContactRequestHandler, MessageHandler, MessageHandlerContext, ProgressMessageOptions, ProgressMessageResult, ReachOutOptions, ReachOutResult, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';

package/dist/realtime.d.ts

@@ -1,4 +1,4 @@
-import { type AgentContext, type CanonClient, type ContactAddedPayload, type ContactApprovedPayload, type ContactRemovedPayload, type ContactRequestPayload } from '@canonmsg/core';
+import { type AgentContext, type CanonClient, type ContactAddedPayload, type ContactApprovedPayload, type ContactRemovedPayload, type ContactRequestPayload, type ConversationUpdatedPayload } from '@canonmsg/core';
 import { Debouncer } from './debouncer.js';
 /**
  * Wraps @canonmsg/core's CanonStream with SDK-specific features:
@@ -15,6 +15,7 @@ export declare class RealtimeManager {
     private onContactApproved;
     private onContactAdded;
     private onContactRemoved;
+    private onConversationUpdated;
     private onConnected;
     private onDisconnected;
     constructor(apiKey: string, debouncer: Debouncer, agentId: string, streamUrl?: string, apiClient?: CanonClient);
@@ -27,6 +28,7 @@ export declare class RealtimeManager {
         onContactAdded?: (payload: ContactAddedPayload) => void;
         onContactRemoved?: (payload: ContactRemovedPayload) => void;
     }): void;
+    setConversationUpdatedHandler(cb: (payload: ConversationUpdatedPayload) => void): void;
     setConnectionHandlers(handlers: {
         onConnected?: () => void;
         onDisconnected?: () => void;

package/dist/realtime.js

@@ -14,6 +14,7 @@ export class RealtimeManager {
     onContactApproved = null;
     onContactAdded = null;
     onContactRemoved = null;
+    onConversationUpdated = null;
     onConnected = null;
     onDisconnected = null;
     constructor(apiKey, debouncer, agentId, streamUrl, apiClient) {
@@ -30,6 +31,7 @@ export class RealtimeManager {
                     const message = {
                         id: m.id,
                         senderId: m.senderId,
+                        ...(m.senderName ? { senderName: m.senderName } : {}),
                         senderType: m.senderType ?? 'human',
                         isOwner: m.isOwner ?? false,
                         contentType: m.contentType ?? 'text',
@@ -67,6 +69,9 @@ export class RealtimeManager {
                 onContactRemoved: (payload) => {
                     this.onContactRemoved?.(payload);
                 },
+                onConversationUpdated: (payload) => {
+                    this.onConversationUpdated?.(payload);
+                },
                 onConnected: () => {
                     // Reset backoff is handled internally by CanonStream
                     this.onConnected?.();
@@ -91,6 +96,9 @@ export class RealtimeManager {
         this.onContactAdded = handlers.onContactAdded ?? null;
         this.onContactRemoved = handlers.onContactRemoved ?? null;
     }
+    setConversationUpdatedHandler(cb) {
+        this.onConversationUpdated = cb;
+    }
     setConnectionHandlers(handlers) {
         this.onConnected = handlers.onConnected ?? null;
         this.onDisconnected = handlers.onDisconnected ?? null;

package/dist/types.d.ts

@@ -1,5 +1,5 @@
-export type { AddMemberResult, AgentClientType, CanonRuntimeDescriptor, CanonMessage, CanonConversation, CanonContact, CanonContactRequest, CanonResolveAdmissionResult, ContactAddedPayload, ContactRemovedPayload, ContactSource, AgentContext, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonSelfContext, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, SessionConfig, CreateConversationOptions, TurnLifecycleState, } from '@canonmsg/core';
-import type { AddMemberResult, CanonMessage, CanonConversation, CanonRuntimeActionDispatch, SendMessageOptions, SendContextualSelfContextInput, SessionConfig } from '@canonmsg/core';
+export type { AddMemberResult, AgentClientType, CanonGroupContext, CanonRuntimeDescriptor, CanonMessage, CanonConversation, CanonContact, CanonContactRequest, CanonResolveAdmissionResult, ContactAddedPayload, ContactRemovedPayload, ContactSource, AgentContext, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonSelfContext, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, SessionConfig, CreateConversationOptions, TurnLifecycleState, } from '@canonmsg/core';
+import type { AddMemberResult, CanonGroupContext, CanonMessage, CanonConversation, ContactCardPayload, CanonRuntimeActionDispatch, SendMessageOptions, SendContextualSelfContextInput, SessionConfig } from '@canonmsg/core';
 import type { MaterializeMediaOptions, MaterializedCanonAttachment, ReplyWithFileOptions, UploadMediaFileOptions } from './media.js';
 export interface ProgressMessageOptions extends SendMessageOptions {
     /**
@@ -39,6 +39,8 @@ export interface MessageHandlerContext {
     history: CanonMessage[];
     conversationId: string;
     conversation: CanonConversation;
+    /** Lightweight group awareness, present for group conversations. */
+    groupContext?: CanonGroupContext;
     replyFinal: (text: string, options?: SendMessageOptions) => Promise<{
         messageId: string;
     }>;
@@ -67,8 +69,12 @@ export interface MessageHandlerContext {
     } | {
         targetUserId: string;
     }, text: string, options: Omit<import('@canonmsg/core').SendContextualMessageOptions, 'sourceConversationId' | 'targetConversationId' | 'targetUserId' | 'text'>) => Promise<import('@canonmsg/core').SendContextualMessageResult>;
+    /** Reach a contact card from this conversation; contextual reach-outs use this conversation as source. */
+    reachOut: (card: ContactCardPayload, options?: Omit<ReachOutOptions, 'sourceConversationId'>) => Promise<ReachOutResult>;
     /** Trusted agent identity & access context */
     agent: import('@canonmsg/core').AgentContext;
+    /** Active private self-context to continue for this turn, if Canon supplied one. */
+    activeSelfContextId: string | null;
     /** Canon-provided private context explaining this agent's cross-session actions. */
     selfContexts?: import('@canonmsg/core').CanonSelfContext[];
     /** Canon-managed local media access for the current conversation. */
@@ -156,12 +162,15 @@ export type ReachOutResult = {
     status: 'messaged';
     conversationId: string;
     messageId?: string;
+    selfContextId?: string;
 } | {
     status: 'requested';
     requestId: string | null;
+    deferredIntentId?: string | null;
 } | {
     status: 'pending';
     requestId: string | null;
+    deferredIntentId?: string | null;
 } | {
     status: 'setup_required';
     reason: string;

package/package.json

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