@canonmsg/agent-sdk 8.8.0 → 8.9.0

package/README.md

@@ -53,12 +53,29 @@ The only runtime dependency is `@canonmsg/core`, which npm installs for you. Eve
 | `sessions` | `SessionOptions` | `undefined` | Enable per-conversation session queues and persistent metadata |
 | `clientType` | `AgentClientType` | `'generic'` | Agent runtime label used for Canon capability detection |
 | `runtimeDescriptor` | `CanonRuntimeDescriptor` | minimal generic descriptor | Optional setup/live controls and runtime capability metadata for Canon UI |
+| `ownerBoundCommunication` | `{ enabled: true, lifecycleStore? }` | `undefined` | Opt into owner-foreground `ctx.reachOut`, truthful reach-out capabilities, and terminal contact lifecycle context. Supply a durable store when the SDK host must retain events across process restarts. |
 | `runtimeControls` | `RuntimeControlHandlers` | `undefined` | Optional `onInterrupt` / `onStopAndDrop` / `onNewSession` handlers for Canon working-state controls |
 | `runtimeControlSurface` | `'agent' \| 'host'` | `'agent'` | Runtime publishing surface. Use `host` when this SDK agent owns live runtime controls. |
 | `runtimePrimitives` | `RuntimePrimitiveHandlers` | `undefined` | Optional typed primitive command handlers for descriptor-backed runtime commands |
 | `sessionState` | `boolean` | `false` | Publish runtime-applied state to the canonical agent-session snapshot |
 | `turnVerbosity` | `'verbose' \| 'quiet' \| 'auto'` or `{ direct?, group? }` | `'auto'` | How much of a turn's middle readers see. See [Turn verbosity](#turn-verbosity). |
 
+### Owner-bound agent introductions
+
+Enable `ownerBoundCommunication` only when your handler is the model-facing
+foreground surface. In that mode, `ctx.reachOut` requires an owner-authored
+source message and visible text, binds replies to the replied contact card, and
+rejects model-selected session setup or hidden self-context. Programmatic
+`agent.reachOut(...)` remains available for application-controlled workflows.
+
+Terminal outbound contact-request phases are deduplicated and exposed through
+`ctx.contactLifecycleEvents` on the next natural owner turn in the source
+conversation. The store records an initial baseline without replaying historical
+outcomes; persist its baseline, dedupe keys, and pending rows when restart
+recovery matters. The default store is process-local. Lifecycle events never
+invoke the message handler on their own, and `connected` means Canon has already
+delivered the opener.
+
 ### Optional runtime controls
 
 Generic SDK agents publish no setup controls by default. If your SDK runtime has local workspace access, you can opt in by publishing a descriptor with explicit project choices:
@@ -290,9 +307,18 @@ agent.on('contactRequest', (request) => {
 agent.on('contactApproved', (request) => {
   console.log('Request approved:', request.id);
 });
+
+agent.on('contactRequestUpdated', (request) => {
+  console.log('Outbound request phase:', request.phase);
+});
 ```
 
-These are awareness callbacks only. Canon still routes approval and rejection for agent-targeted requests through the human owner's UI/callable flow.
+These are awareness callbacks only. Canon still routes approval, rejection,
+and any coding-session setup for agent-targeted requests through the human
+owner's UI/callable flow. Outbound phases intentionally hide delivery internals:
+`awaiting_owner`, `starting`, `connected`, `rejected`, `expired`, `cancelled`,
+or `failed`. A connected update includes the conversation id and means the
+parked opener was already delivered; do not send it again.
 
 ### Turn-aware example
 
@@ -335,6 +361,8 @@ await agent.contacts.list();                       // CanonContact[]
 await agent.contacts.get(contactId);               // CanonContact | null
 await agent.contacts.remove(contactId);
 await agent.contacts.request(targetUserId, 'why I am reaching out');
+await agent.contacts.listRequests({ direction: 'outbound', includeResolved: true });
+await agent.contacts.cancelRequest(requestId);
 
 await agent.users.block(userId);
 await agent.users.unblock(userId);

package/dist/canon-agent.d.ts

@@ -1,5 +1,5 @@
-import { type AddMemberResult, type CanonContact, type CanonConversation, type CanonConversationsPage, type CanonConversationsPageOptions, type CreateConversationResult, type CanonRuntimeActivityItem, type CanonRuntimeCommandDescriptor, type CanonRuntimeFact, type CanonRuntimePrimitiveId, type ContactCardPayload, type ClearRuntimeActivityOptions, type CreateContactRequestResult, type CanonVoiceSession, type CanonVoiceSessionToken, type CreateVoiceSessionOptions, type VoiceSessionEventPayload } from '@canonmsg/core';
-import type { CanonAgentConnectionOptions, CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, CreateConversationOptions, MessageHandler, MessageUpdatedHandler, ParticipationSuppressedHandler, ReachOutOptions, ReachOutResult, ContactRequestHandler, RuntimeSignalHandler, RuntimePrimitiveHandler } from './types.js';
+import { type AddMemberResult, type CanonContact, type CanonContactRequest, type ContactRequestListOptions, type CanonConversation, type CanonConversationsPage, type CanonConversationsPageOptions, type CreateConversationResult, type CanonRuntimeActivityItem, type CanonRuntimeCommandDescriptor, type CanonRuntimeFact, type CanonRuntimePrimitiveId, type ContactCardPayload, type ClearRuntimeActivityOptions, type CreateContactRequestResult, type CanonVoiceSession, type CanonVoiceSessionToken, type CreateVoiceSessionOptions, type VoiceSessionEventPayload } from '@canonmsg/core';
+import type { CanonAgentConnectionOptions, CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, CreateConversationOptions, MessageHandler, MessageUpdatedHandler, ParticipationSuppressedHandler, ReachOutOptions, ReachOutResult, ContactRequestHandler, ContactRequestUpdatedHandler, RuntimeSignalHandler, RuntimePrimitiveHandler } from './types.js';
 /**
  * Contact-graph operations exposed under `agent.contacts`. Wraps the REST
  * endpoints in CanonClient — the same surface a human user would hit through
@@ -10,6 +10,11 @@ export interface AgentContactsAPI {
     get(contactId: string): Promise<CanonContact | null>;
     remove(contactId: string): Promise<void>;
     request(targetUserId: string, message?: string | null): Promise<CreateContactRequestResult>;
+    listRequests(options?: ContactRequestListOptions): Promise<CanonContactRequest[]>;
+    cancelRequest(requestId: string): Promise<{
+        status: 'cancelled';
+        requestId: string;
+    }>;
 }
 /**
  * User-level moderation actions exposed under `agent.users`.
@@ -42,6 +47,7 @@ export declare class CanonAgent {
     private sessionManager;
     private handler;
     private contactRequestHandler;
+    private contactRequestUpdatedHandler;
     private contactApprovedHandler;
     private contactAddedHandler;
     private contactRemovedHandler;
@@ -63,6 +69,7 @@ export declare class CanonAgent {
     /** Conversation discovery for choosing existing sessions intentionally. */
     readonly conversations: AgentConversationsAPI;
     private readonly reachOutInFlight;
+    private readonly contactLifecycleStore;
     private agentId;
     private agentContext;
     private approvalManager;
@@ -104,6 +111,7 @@ export declare class CanonAgent {
     on(event: 'message', handler: MessageHandler): void;
     on(event: 'messageUpdated', handler: MessageUpdatedHandler): void;
     on(event: 'contactRequest', handler: ContactRequestHandler): void;
+    on(event: 'contactRequestUpdated', handler: ContactRequestUpdatedHandler): void;
     on(event: 'contactApproved', handler: ContactRequestHandler): void;
     on(event: 'contactAdded', handler: ContactAddedHandler): void;
     on(event: 'contactRemoved', handler: ContactRemovedHandler): void;
@@ -171,6 +179,8 @@ export declare class CanonAgent {
         attachment: import('@canonmsg/core').MediaAttachment;
     }>;
     private handleContactRequestEvent;
+    private recordAndHandleContactLifecycleEvent;
+    private reconcileContactLifecycleInbox;
     private handleContactGraphEvent;
     private handleParticipationSuppressedEvent;
     private handleMessageUpdatedEvent;

package/dist/canon-agent.js

@@ -1,4 +1,4 @@
-import { ApprovalManager, RuntimeRequestManager, runtimeInputDescriptor, runtimeCardDescriptor, CanonClient, ControlChannelPoller, buildCanonTurnContextV2, buildCanonGroupContext, buildParticipationHistorySnapshot, createTurnOutputController, createRuntimeStatePublisher, createTypingStatusPublisher, diffCanonMemberIds, FINAL_MESSAGE_HANDOFF_MS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildRuntimeCardOutcome, buildRuntimeInputOutcome, initRTDBAuth, isChunkedSendMessageError, normalizeRuntimeCommandDescriptors, normalizeTurnMetadata, normalizeTurnVerbosityConversationType, reachOutToCanonContact, reportNoReplyOutcome, resolveCanonReplyContext, resolveMessageActiveSelfContextId, resolveRuntimeProvenance, resolveTurnVerbosity, selectActiveSelfContexts, renderCanonHostInboundContent, resolveCanonRuntimeConnection, sendMessageWithRetryChunked, shouldPublishTurnTrail, splitTextByUtf8Bytes, verifyCanonRuntimeConnection, } from '@canonmsg/core';
+import { ApprovalManager, RuntimeRequestManager, runtimeInputDescriptor, runtimeCardDescriptor, CanonClient, ControlChannelPoller, buildCanonTurnContextV2, buildCanonGroupContext, buildParticipationHistorySnapshot, createTurnOutputController, createRuntimeStatePublisher, createTypingStatusPublisher, diffCanonMemberIds, contactRequestLifecycleEventKey, reconcileContactLifecycleEvents, FINAL_MESSAGE_HANDOFF_MS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildRuntimeCardOutcome, buildRuntimeInputOutcome, initRTDBAuth, isChunkedSendMessageError, normalizeRuntimeCommandDescriptors, normalizeTurnMetadata, normalizeTurnVerbosityConversationType, reachOutToCanonContact, reportNoReplyOutcome, resolveCanonReplyContext, resolveMessageActiveSelfContextId, resolveRuntimeProvenance, resolveTurnVerbosity, selectActiveSelfContexts, renderCanonHostInboundContent, resolveCanonRuntimeConnection, sendMessageWithRetryChunked, shouldPublishTurnTrail, splitTextByUtf8Bytes, verifyCanonRuntimeConnection, } from '@canonmsg/core';
 import { createHash, randomUUID } from 'node:crypto';
 import { AuthManager } from './auth.js';
 import { Debouncer } from './debouncer.js';
@@ -15,6 +15,34 @@ const SDK_MESSAGE_ID_READABLE_MAX = 120;
 /** Canon's message id ceiling, matching core's chunked sender. */
 const CANON_MESSAGE_ID_MAX = 160;
 const SDK_PARTIAL_FINAL_NOTICE = 'This reply stops short because Canon could not deliver the remaining text.';
+class InMemoryContactLifecycleStore {
+    keys = new Set();
+    pending = [];
+    baselineComplete = false;
+    record(request, options = {}) {
+        const key = contactRequestLifecycleEventKey(request);
+        if (!key || this.keys.has(key))
+            return false;
+        this.keys.add(key);
+        if (options.pending !== false)
+            this.pending.push(request);
+        while (this.keys.size > 512)
+            this.keys.delete(this.keys.values().next().value);
+        this.pending = this.pending.slice(-100);
+        return true;
+    }
+    take(sourceConversationId) {
+        const taken = this.pending.filter((request) => request.sourceConversationId === sourceConversationId);
+        this.pending = this.pending.filter((request) => request.sourceConversationId !== sourceConversationId);
+        return taken;
+    }
+    isBaselineComplete() {
+        return this.baselineComplete;
+    }
+    completeBaseline() {
+        this.baselineComplete = true;
+    }
+}
 const SDK_RUNTIME_CAPABILITIES = {
     supportsInterrupt: false,
     supportsInputInterrupt: false,
@@ -255,6 +283,7 @@ export class CanonAgent {
     sessionManager = null;
     handler = null;
     contactRequestHandler = null;
+    contactRequestUpdatedHandler = null;
     contactApprovedHandler = null;
     contactAddedHandler = null;
     contactRemovedHandler = null;
@@ -276,6 +305,7 @@ export class CanonAgent {
     /** Conversation discovery for choosing existing sessions intentionally. */
     conversations;
     reachOutInFlight = new Map();
+    contactLifecycleStore;
     agentId = null;
     agentContext = null;
     approvalManager = null;
@@ -322,6 +352,9 @@ export class CanonAgent {
             rtdbUrl: this.runtimeConnection.rtdbUrl,
             firebaseApiKey: this.runtimeConnection.firebaseWebApiKey,
         };
+        this.contactLifecycleStore = options.ownerBoundCommunication?.enabled
+            ? options.ownerBoundCommunication.lifecycleStore ?? new InMemoryContactLifecycleStore()
+            : null;
         this.apiClient = new CanonClient(this.options.apiKey, this.options.baseUrl);
         this.typingSignals = createTypingStatusPublisher({
             setTyping: (conversationId, typing, status) => status
@@ -336,6 +369,8 @@ export class CanonAgent {
             get: (contactId) => apiClient.getContact(contactId),
             remove: (contactId) => apiClient.deleteContact(contactId),
             request: (targetUserId, message) => apiClient.createContactRequest(targetUserId, message ?? null),
+            listRequests: (options) => apiClient.listContactRequests(options),
+            cancelRequest: (requestId) => apiClient.cancelContactRequest(requestId),
         };
         this.users = {
             block: (userId) => apiClient.blockUser(userId),
@@ -463,6 +498,10 @@ export class CanonAgent {
             this.contactRequestHandler = handler;
             return;
         }
+        if (event === 'contactRequestUpdated') {
+            this.contactRequestUpdatedHandler = handler;
+            return;
+        }
         if (event === 'contactApproved') {
             this.contactApprovedHandler = handler;
             return;
@@ -663,6 +702,7 @@ export class CanonAgent {
         try {
             this.agentContext = await this.apiClient.getAgentMe();
             this.ensureApprovalManager(this.agentContext);
+            await this.reconcileContactLifecycleInbox();
         }
         catch {
             console.warn('[canon-sdk] Failed to fetch agent context — owner/access info unavailable');
@@ -709,6 +749,9 @@ export class CanonAgent {
             onContactRequest: (request) => {
                 void this.handleContactRequestEvent(this.contactRequestHandler, request);
             },
+            onContactRequestUpdated: (request) => {
+                void this.recordAndHandleContactLifecycleEvent(request);
+            },
             onContactApproved: (request) => {
                 void this.handleContactRequestEvent(this.contactApprovedHandler, request);
             },
@@ -738,11 +781,19 @@ export class CanonAgent {
         rtm.setConnectionHandlers({
             onConnected: () => {
                 this.startRuntimeHeartbeat();
+                void this.reconcileContactLifecycleInbox().catch((error) => {
+                    console.error('[canon-sdk] Contact lifecycle reconciliation failed:', error);
+                });
                 if (!this.sseConnectedLogged) {
                     this.sseConnectedLogged = true;
                     console.log('[canon-sdk] SSE stream connected');
                 }
             },
+            onReplayExpired: () => {
+                void this.reconcileContactLifecycleInbox().catch((error) => {
+                    console.error('[canon-sdk] Contact lifecycle reconciliation failed:', error);
+                });
+            },
             onDisconnected: () => this.stopRuntimeHeartbeat(),
         });
         this.realtimeManager = rtm;
@@ -818,6 +869,37 @@ export class CanonAgent {
             console.error('[canon-sdk] Contact-request handler failed:', error instanceof Error ? error.message : error);
         }
     }
+    async recordAndHandleContactLifecycleEvent(request) {
+        if (this.contactLifecycleStore
+            && request.requesterId === this.agentId
+            && request.sourceConversationId) {
+            await this.contactLifecycleStore.record(request);
+        }
+        await this.handleContactRequestEvent(this.contactRequestUpdatedHandler, request);
+    }
+    async reconcileContactLifecycleInbox() {
+        if (!this.contactLifecycleStore || !this.agentId)
+            return;
+        const requests = await this.apiClient.listContactRequests({
+            direction: 'outbound',
+            includeResolved: true,
+            limit: 100,
+        });
+        if (!await this.contactLifecycleStore.isBaselineComplete()) {
+            await reconcileContactLifecycleEvents({
+                requests,
+                requesterId: this.agentId,
+                record: (request) => this.contactLifecycleStore.record(request, { pending: false }),
+            });
+            await this.contactLifecycleStore.completeBaseline();
+            return;
+        }
+        await reconcileContactLifecycleEvents({
+            requests,
+            requesterId: this.agentId,
+            record: (request) => this.contactLifecycleStore.record(request),
+        });
+    }
     async handleContactGraphEvent(handler, payload) {
         if (!handler)
             return;
@@ -934,6 +1016,13 @@ export class CanonAgent {
         }
         return {
             ...source,
+            admissionActions: {
+                blockUser: source.admissionActions?.blockUser === true,
+                unblockUser: source.admissionActions?.unblockUser === true,
+                removeContact: source.admissionActions?.removeContact === true,
+                requestContact: this.options.ownerBoundCommunication?.enabled === true,
+                reachOut: this.options.ownerBoundCommunication?.enabled === true,
+            },
             supportsInterrupt: hasInterrupt,
             supportsInputInterrupt: source.supportsInputInterrupt === false ? false : hasInterrupt,
             commands: normalizeRuntimeCommandDescriptors(commands),
@@ -1542,6 +1631,9 @@ export class CanonAgent {
                 for (const m of history) {
                     m.isOwner = m.senderId === ownerId;
                 }
+                for (const m of hydratedMessages) {
+                    m.isOwner = m.senderId === ownerId;
+                }
             }
             const latestMessage = hydratedMessages[hydratedMessages.length - 1] ?? null;
             const triggeringHumanId = latestMessage?.senderType === 'human'
@@ -1550,6 +1642,9 @@ export class CanonAgent {
             let replyContext = latestMessage
                 ? resolveCanonReplyContext({ message: latestMessage, messages: history })
                 : null;
+            const contactLifecycleEvents = latestMessage?.isOwner && this.contactLifecycleStore
+                ? await this.contactLifecycleStore.take(conversationId)
+                : [];
             const resolvedActiveSelfContextId = resolveMessageActiveSelfContextId({
                 messageId: latestMessage?.id,
                 activeSelfContextIdByMessageId: page.activeSelfContextIdByMessageId,
@@ -1716,10 +1811,44 @@ export class CanonAgent {
                     },
                 },
             });
-            const reachOut = (card, options) => this.reachOut(card, {
-                ...(options ?? {}),
-                sourceConversationId: conversationId,
-            });
+            const reachOut = (card, options) => {
+                if (!this.options.ownerBoundCommunication?.enabled) {
+                    return this.reachOut(card, {
+                        ...(options ?? {}),
+                        sourceConversationId: conversationId,
+                    });
+                }
+                if (!latestMessage?.isOwner || !latestMessage.id) {
+                    return Promise.reject(new Error('Owner-bound reachOut requires an owner-authored foreground message.'));
+                }
+                if (options?.sessionConfig != null
+                    || options?.sessionSelection != null
+                    || options?.selfContext != null) {
+                    return Promise.reject(new Error('Owner-bound reachOut does not accept model-selected session configuration or hidden context.'));
+                }
+                const boundCard = replyContext?.found && replyContext.contactCard
+                    ? replyContext.contactCard
+                    : card;
+                const text = options?.text?.trim();
+                if (!text)
+                    return Promise.reject(new Error('Owner-bound reachOut requires visible text.'));
+                return this.apiClient.sendTo({
+                    ...(boundCard.canonContactId
+                        ? { canonContactId: boundCard.canonContactId }
+                        : { targetUserId: boundCard.userId }),
+                    sourceConversationId: conversationId,
+                    text,
+                    ...(options?.requestMessage ? { requestMessage: options.requestMessage } : {}),
+                    messageOptions: {
+                        metadata: {
+                            sourceConversationId: conversationId,
+                            sourceMessageId: latestMessage.id,
+                            turnId,
+                            turnSemantics: 'turn_complete',
+                        },
+                    },
+                });
+            };
             const requestApproval = async (request) => {
                 throwIfAborted();
                 const manager = this.ensureApprovalManager(agent);
@@ -2080,6 +2209,7 @@ export class CanonAgent {
                 messages: hydratedMessages,
                 history,
                 replyContext,
+                contactLifecycleEvents,
                 conversationId,
                 conversation,
                 ...(groupContext ? { groupContext } : {}),

package/dist/index.d.ts

@@ -7,5 +7,5 @@ export { DEFAULT_ANTHROPIC_REQUEST_HEADROOM_BYTES, DEFAULT_MEDIA_CACHE_DIR, DEFA
 export type { AnthropicImageBlock, AnthropicImageBudgetOptions, AnthropicImageMimeType, MaterializeMediaOptions, MaterializedCanonAttachment, MaterializedCanonReplyContext, ReplyWithFileOptions, UploadMediaFileOptions, } from './media.js';
 export type { SessionConfig, Session } from './session-manager.js';
 export type { CanonAgentTurnVerbosityOption } from './turn-verbosity-option.js';
-export type { AgentContext, CanonGroupContext, CanonKnownRecentParticipant, CanonMembershipChange, CanonContactRequest, GroupInviteRequirements, CanonMessage, CanonConversation, CanonConversationsPage, CanonConversationsPageOptions, CanonReplyContext, CanonSelfContext, CanonTurnContextV2, CanonRuntimeDescriptor, MessageUpdatedPayload, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, CreateConversationOptions, CreateConversationResult, DirectSessionSelection, TurnVerbosity, TurnVerbosityConfig, } from '@canonmsg/core';
-export type { CanonAgentConnectionOptions, CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, ContactRequestHandler, FinalMessageResult, MessageHandler, MessageHandlerContext, MessageUpdatedHandler, ParticipationSuppressedHandler, ProgressMessageOptions, ProgressMessageResult, ReachOutOptions, ReachOutResult, RuntimeApprovalRequest, RuntimeInputRequest, RuntimeInputResult, RuntimeControlSurface, RuntimePrimitiveContext, RuntimePrimitiveHandler, RuntimePrimitiveHandlers, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';
+export type { AgentContext, CanonGroupContext, CanonKnownRecentParticipant, CanonMembershipChange, CanonContactRequest, ContactRequestUpdatedPayload, ContactRequestListOptions, ContactRequestRequirements, ContactRequestLifecyclePhase, GroupInviteRequirements, CanonMessage, CanonConversation, CanonConversationsPage, CanonConversationsPageOptions, CanonReplyContext, CanonSelfContext, CanonTurnContextV2, CanonRuntimeDescriptor, MessageUpdatedPayload, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, CreateConversationOptions, CreateConversationResult, DirectSessionSelection, TurnVerbosity, TurnVerbosityConfig, } from '@canonmsg/core';
+export type { CanonAgentConnectionOptions, CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, ContactRequestHandler, ContactRequestUpdatedHandler, ContactLifecycleStore, FinalMessageResult, MessageHandler, MessageHandlerContext, MessageUpdatedHandler, ParticipationSuppressedHandler, ProgressMessageOptions, ProgressMessageResult, ReachOutOptions, ReachOutResult, RuntimeApprovalRequest, RuntimeInputRequest, RuntimeInputResult, RuntimeControlSurface, RuntimePrimitiveContext, RuntimePrimitiveHandler, RuntimePrimitiveHandlers, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';

package/dist/realtime.d.ts

@@ -1,4 +1,4 @@
-import { type AgentContext, type ContactAddedPayload, type ContactApprovedPayload, type ContactRemovedPayload, type ContactRequestPayload, type ConversationUpdatedPayload, type MessageUpdatedPayload, type ParticipationSuppressedPayload, type VoiceSessionEventPayload } from '@canonmsg/core';
+import { type AgentContext, type ContactAddedPayload, type ContactApprovedPayload, type ContactRemovedPayload, type ContactRequestPayload, type ContactRequestUpdatedPayload, type ConversationUpdatedPayload, type MessageUpdatedPayload, type ParticipationSuppressedPayload, type VoiceSessionEventPayload } from '@canonmsg/core';
 import { Debouncer } from './debouncer.js';
 /**
  * Wraps @canonmsg/core's CanonStream with SDK-specific features:
@@ -16,6 +16,7 @@ export declare class RealtimeManager {
     private suppressedSseErrorCount;
     private onAgentContext;
     private onContactRequest;
+    private onContactRequestUpdated;
     private onContactApproved;
     private onContactAdded;
     private onContactRemoved;
@@ -25,6 +26,7 @@ export declare class RealtimeManager {
     private onMessageDeleted;
     private onConnected;
     private onDisconnected;
+    private onReplayExpired;
     private onCallStarted;
     private onCallEnded;
     constructor(apiKey: string, debouncer: Debouncer, agentId: string, streamUrl?: string, options?: {
@@ -37,6 +39,7 @@ export declare class RealtimeManager {
     setOnAgentContext(cb: (ctx: AgentContext) => void): void;
     setContactRequestHandlers(handlers: {
         onContactRequest?: (payload: ContactRequestPayload) => void;
+        onContactRequestUpdated?: (payload: ContactRequestUpdatedPayload) => void;
         onContactApproved?: (payload: ContactApprovedPayload) => void;
     }): void;
     setContactGraphHandlers(handlers: {
@@ -58,6 +61,7 @@ export declare class RealtimeManager {
     setConnectionHandlers(handlers: {
         onConnected?: () => void;
         onDisconnected?: () => void;
+        onReplayExpired?: () => void;
     }): void;
     setCallHandlers(handlers: {
         onCallStarted?: (payload: VoiceSessionEventPayload) => void;

package/dist/realtime.js

@@ -17,6 +17,7 @@ export class RealtimeManager {
     suppressedSseErrorCount = 0;
     onAgentContext = null;
     onContactRequest = null;
+    onContactRequestUpdated = null;
     onContactApproved = null;
     onContactAdded = null;
     onContactRemoved = null;
@@ -26,6 +27,7 @@ export class RealtimeManager {
     onMessageDeleted = null;
     onConnected = null;
     onDisconnected = null;
+    onReplayExpired = null;
     onCallStarted = null;
     onCallEnded = null;
     constructor(apiKey, debouncer, agentId, streamUrl, options) {
@@ -102,6 +104,9 @@ export class RealtimeManager {
                 onContactRequest: (payload) => {
                     this.onContactRequest?.(payload);
                 },
+                onContactRequestUpdated: (payload) => {
+                    this.onContactRequestUpdated?.(payload);
+                },
                 onContactApproved: (payload) => {
                     this.onContactApproved?.(payload);
                 },
@@ -125,6 +130,7 @@ export class RealtimeManager {
                 },
                 onReplayExpired: (payload) => {
                     console.error(`[canon-sdk] SSE replay window expired${payload.lastAvailableId ? ` (oldest available event: ${payload.lastAvailableId})` : ''}; missed history is available via explicit REST fetch`);
+                    this.onReplayExpired?.();
                 },
                 onError: (err) => {
                     this.logSseError(err);
@@ -175,6 +181,7 @@ export class RealtimeManager {
     }
     setContactRequestHandlers(handlers) {
         this.onContactRequest = handlers.onContactRequest ?? null;
+        this.onContactRequestUpdated = handlers.onContactRequestUpdated ?? null;
         this.onContactApproved = handlers.onContactApproved ?? null;
     }
     setContactGraphHandlers(handlers) {
@@ -201,6 +208,7 @@ export class RealtimeManager {
     setConnectionHandlers(handlers) {
         this.onConnected = handlers.onConnected ?? null;
         this.onDisconnected = handlers.onDisconnected ?? null;
+        this.onReplayExpired = handlers.onReplayExpired ?? null;
     }
     setCallHandlers(handlers) {
         this.onCallStarted = handlers.onCallStarted ?? null;

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-export type { AddMemberResult, GroupInviteRequirements, AgentClientType, CanonGroupContext, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeDescriptor, CanonRuntimeFact, CanonRuntimeFactGroup, CanonRuntimePrimitiveId, CanonRuntimeProvenance, CanonTurnContextV2, CanonMessage, CanonConversation, CanonReplyContext, CanonContact, CanonContactRequest, CanonResolveAdmissionResult, ContactAddedPayload, ContactRemovedPayload, ContactSource, AgentContext, ResolveAdmissionTargetInput, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonSelfContext, CreateConversationResult, DirectSessionSelection, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, SessionConfig, VerbSessionConfig, CreateConversationOptions, TurnLifecycleState, TurnOutputBlock, TurnOutputBlockInput, ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalRisk, ApprovalReplyMetadata, ApprovalOutcomeMetadata, RuntimeInputChoice, RuntimeInputAnswers, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, RuntimeCardNativeMetadata, RuntimeCardV1, ResumableMediaUploadResult, MediaAttachment, VideoProcessingStatus, VideoProcessingErrorCode, SessionRule, ApprovalResult, } from '@canonmsg/core';
+export type { AddMemberResult, ContactRequestListOptions, ContactRequestRequirements, ContactRequestLifecyclePhase, GroupInviteRequirements, AgentClientType, CanonGroupContext, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeDescriptor, CanonRuntimeFact, CanonRuntimeFactGroup, CanonRuntimePrimitiveId, CanonRuntimeProvenance, CanonTurnContextV2, CanonMessage, CanonConversation, CanonReplyContext, CanonContact, CanonContactRequest, ContactRequestUpdatedPayload, CanonResolveAdmissionResult, ContactAddedPayload, ContactRemovedPayload, ContactSource, AgentContext, ResolveAdmissionTargetInput, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonSelfContext, CreateConversationResult, DirectSessionSelection, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, SessionConfig, VerbSessionConfig, CreateConversationOptions, TurnLifecycleState, TurnOutputBlock, TurnOutputBlockInput, ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalRisk, ApprovalReplyMetadata, ApprovalOutcomeMetadata, RuntimeInputChoice, RuntimeInputAnswers, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, RuntimeCardNativeMetadata, RuntimeCardV1, ResumableMediaUploadResult, MediaAttachment, VideoProcessingStatus, VideoProcessingErrorCode, SessionRule, ApprovalResult, } from '@canonmsg/core';
 import type { AddMemberResult, CanonGroupContext, CanonMessage, CanonConversation, CanonReplyContext, ContactCardPayload, CanonRuntimeActionDispatch, CanonRuntimePrimitiveId, CanonRuntimeProvenance, CanonTurnContextV2, ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalResult, ApprovalRisk, RuntimeInputChoice, RuntimeInputAnswers, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, RuntimeCardNativeMetadata, RuntimeCardV1, ResumableMediaUploadResult, SendMessageOptions, SendContextualSelfContextInput, VerbSessionConfig, DirectSessionSelection, TurnOutputBlock, TurnOutputBlockInput } from '@canonmsg/core';
 import type { MaterializeMediaOptions, MaterializedCanonAttachment, ReplyWithFileOptions, UploadMediaFileOptions } from './media.js';
 export interface ProgressMessageOptions extends SendMessageOptions {
@@ -152,6 +152,8 @@ export interface MessageHandlerContext {
     history: CanonMessage[];
     /** Resolved message/media content for the latest swipe-reply target, if any. */
     replyContext: CanonReplyContext | null;
+    /** Terminal introduction events retained until this natural owner turn. */
+    contactLifecycleEvents: import('@canonmsg/core').CanonContactRequest[];
     conversationId: string;
     conversation: CanonConversation;
     /** Lightweight group awareness, present for group conversations. */
@@ -310,6 +312,15 @@ export interface CanonAgentOptions extends CanonAgentConnectionOptions {
     clientType?: import('@canonmsg/core').AgentClientType;
     /** Optional runtime descriptor published to Canon for setup/live UI rendering. */
     runtimeDescriptor?: import('@canonmsg/core').CanonRuntimeDescriptor;
+    /**
+     * Opt into the owner-authorized introduction surface advertised to Canon.
+     * Lifecycle events never start a model turn; they are passed to the next
+     * natural owner handler invocation and to onContactRequestUpdated.
+     */
+    ownerBoundCommunication?: {
+        enabled: true;
+        lifecycleStore?: ContactLifecycleStore;
+    };
     /** Optional Canon runtime signal handlers. Enables interrupt controls when provided. */
     runtimeControls?: RuntimeControlHandlers;
     /** Runtime publishing surface. Use `host` when this agent owns live runtime controls. */
@@ -336,6 +347,15 @@ export interface CanonAgentOptions extends CanonAgentConnectionOptions {
     turnVerbosity?: import('./turn-verbosity-option.js').CanonAgentTurnVerbosityOption;
 }
 export type ContactRequestHandler = (request: import('@canonmsg/core').CanonContactRequest) => void | Promise<void>;
+export type ContactRequestUpdatedHandler = ContactRequestHandler;
+export interface ContactLifecycleStore {
+    record(request: import('@canonmsg/core').CanonContactRequest, options?: {
+        pending?: boolean;
+    }): boolean | Promise<boolean>;
+    take(sourceConversationId: string): import('@canonmsg/core').CanonContactRequest[] | Promise<import('@canonmsg/core').CanonContactRequest[]>;
+    isBaselineComplete(): boolean | Promise<boolean>;
+    completeBaseline(): void | Promise<void>;
+}
 export type ContactAddedHandler = (contact: import('@canonmsg/core').ContactAddedPayload) => void | Promise<void>;
 export type ContactRemovedHandler = (payload: import('@canonmsg/core').ContactRemovedPayload) => void | Promise<void>;
 /**

package/package.json

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