@canonmsg/agent-sdk 8.9.0 → 9.0.0

package/README.md

@@ -53,29 +53,12 @@ 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:
@@ -207,8 +190,7 @@ The `message` event handler receives a context object with:
 | `leave` | `() => Promise<void>` | Leave the current group conversation |
 | `react` | `(messageId, emoji) => Promise<void>` | Toggle an emoji reaction |
 | `addMember` / `removeMember` | functions | Manage group members when the agent has permission |
-| `sendContextualMessage` | function | Send into another conversation with private self-context from this conversation |
-| `reachOut` | function | Act on a Canon contact card using live admission resolution |
+| `communicate` | function | Message an existing conversation, start a direct conversation, create a group, or forward an exact message |
 | `agent` | `AgentContext` | Trusted Canon agent identity and access context |
 | `activeSelfContextId` | `string \| null` | Active private self-context id for this turn |
 | `selfContexts` | `CanonSelfContext[] \| undefined` | Private context explaining this agent's cross-session actions |
@@ -307,18 +289,9 @@ 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, 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.
+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
 
@@ -361,8 +334,6 @@ 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);
@@ -536,7 +507,7 @@ A conversation whose type Canon could not determine falls back to verbose, never
 
 **Quiet suppresses**: every `/streaming` publication — the `'Thinking...'` seed and its keepalive, `turn.setThinking/setStreaming/setTool`, `turn.appendDelta`/`appendBlock`/segment updates, `turn.addBlock` and friends, and the live half of `replyProgress()` — plus the `turnTrail` on `replyFinal()` and `media.replyWithFile()`. Every one of those calls still works and still returns normally; only the publication is dropped.
 
-**Quiet does not suppress**: the typing/thinking indicator (which stays up for the turn's whole working phase; while the turn is parked on an approval the clients suppress an agent's dots and the header line carries the state), turn state, `replyFinal()` including every part of a chunked reply, the partial-final notice, `media.replyWithFile()` itself, `turn.setWaitingInput()`'s note, `sendContextualMessage()`, `publishRuntimeActivity()`, approval/input/card requests, and their outcome receipts.
+**Quiet does not suppress**: the typing/thinking indicator (which stays up for the turn's whole working phase; while the turn is parked on an approval the clients suppress an agent's dots and the header line carries the state), turn state, `replyFinal()` including every part of a chunked reply, the partial-final notice, `media.replyWithFile()` itself, `turn.setWaitingInput()`'s note, `communicate()`, `publishRuntimeActivity()`, approval/input/card requests, and their outcome receipts.
 
 **`replyProgress(text, { durable: true })` still posts.** Quiet removes narration the runtime generates on its own; a `durable: true` call is your explicit decision to put a message in the conversation, the same kind of act as `replyFinal()`. Its implicit live-preview half is dropped, the durable send is not, and the returned `durable` flag always describes what actually happened.
 
@@ -561,4 +532,4 @@ Canon caps a single message at 4 KB of UTF-8 text, and rejects anything longer o
 Every other send path passes your text through as-is, so text over the cap still fails there. Notably:
 
 - `media.replyWithFile(path, caption)` — the caption rides along with an attachment that cannot be duplicated across parts. Keep captions short and send long prose as a separate `replyFinal()`.
-- `sendContextualMessage()` and `reachOut({ text })` — a different endpoint with no chunked sender behind it.
+- `communicate()` — a distinct compact cross-conversation operation; keep each message under the cap.

package/dist/canon-agent.d.ts

@@ -1,5 +1,5 @@
-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';
+import { type AddMemberResult, type CanonContact, type CommunicateInput, type CommunicateResult, type CanonConversation, type CanonConversationsPage, type CanonConversationsPageOptions, type CreateGroupOptions, type CreateGroupResult, type CanonRuntimeActivityItem, type CanonRuntimeCommandDescriptor, type CanonRuntimeFact, type CanonRuntimePrimitiveId, type ClearRuntimeActivityOptions, type CanonVoiceSession, type CanonVoiceSessionToken, type CreateVoiceSessionOptions, type VoiceSessionEventPayload } from '@canonmsg/core';
+import type { CanonAgentConnectionOptions, CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, MessageHandler, MessageUpdatedHandler, ParticipationSuppressedHandler, ContactRequestHandler, 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
@@ -9,12 +9,6 @@ export interface AgentContactsAPI {
     list(): Promise<CanonContact[]>;
     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`.
@@ -47,7 +41,6 @@ export declare class CanonAgent {
     private sessionManager;
     private handler;
     private contactRequestHandler;
-    private contactRequestUpdatedHandler;
     private contactApprovedHandler;
     private contactAddedHandler;
     private contactRemovedHandler;
@@ -68,8 +61,6 @@ export declare class CanonAgent {
     readonly users: AgentUsersAPI;
     /** Conversation discovery for choosing existing sessions intentionally. */
     readonly conversations: AgentConversationsAPI;
-    private readonly reachOutInFlight;
-    private readonly contactLifecycleStore;
     private agentId;
     private agentContext;
     private approvalManager;
@@ -111,7 +102,6 @@ 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;
@@ -135,16 +125,13 @@ export declare class CanonAgent {
     publishRuntimeActivity(conversationId: string, item: CanonRuntimeActivityItem): Promise<void>;
     clearRuntimeActivity(conversationId: string, options?: ClearRuntimeActivityOptions): Promise<void>;
     /**
-     * Resolve admission live for a target user (typically read off a shared
-     * contact card) and route into either an immediate message or a contact
-     * request. Never reads `card.accessLevel` — that snapshot is stale by the
-     * time an LLM acts on it. Instead defers to `resolveAdmission` so the
-     * answer reflects the target's *current* inbound policy.
+     * Message an existing Canon conversation or start/continue a direct one.
+     * Policy and admission are enforced by Canon; this method deliberately
+     * exposes no runtime configuration or trusted source-context fields.
      */
-    reachOut(card: ContactCardPayload, options?: ReachOutOptions): Promise<ReachOutResult>;
-    private executeReachOut;
+    communicate(input: CommunicateInput): Promise<CommunicateResult>;
     start(): Promise<void>;
-    createConversation(options: CreateConversationOptions): Promise<CreateConversationResult>;
+    createGroup(options: CreateGroupOptions): Promise<CreateGroupResult>;
     /** Start (or rejoin) a call in a conversation and get the room token. */
     startCall(options: CreateVoiceSessionOptions): Promise<CanonVoiceSessionToken>;
     /** Join an active call session and get the room token. */
@@ -179,8 +166,6 @@ 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, 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 { 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, 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,34 +15,6 @@ 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,
@@ -283,7 +255,6 @@ export class CanonAgent {
     sessionManager = null;
     handler = null;
     contactRequestHandler = null;
-    contactRequestUpdatedHandler = null;
     contactApprovedHandler = null;
     contactAddedHandler = null;
     contactRemovedHandler = null;
@@ -304,8 +275,6 @@ export class CanonAgent {
     users;
     /** Conversation discovery for choosing existing sessions intentionally. */
     conversations;
-    reachOutInFlight = new Map();
-    contactLifecycleStore;
     agentId = null;
     agentContext = null;
     approvalManager = null;
@@ -352,9 +321,6 @@ 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
@@ -368,9 +334,6 @@ export class CanonAgent {
             list: () => apiClient.listContacts(),
             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),
@@ -498,10 +461,6 @@ export class CanonAgent {
             this.contactRequestHandler = handler;
             return;
         }
-        if (event === 'contactRequestUpdated') {
-            this.contactRequestUpdatedHandler = handler;
-            return;
-        }
         if (event === 'contactApproved') {
             this.contactApprovedHandler = handler;
             return;
@@ -585,75 +544,12 @@ export class CanonAgent {
         await this.requireRuntimeStatePublisher().clearRuntimeActivity(conversationId, options);
     }
     /**
-     * Resolve admission live for a target user (typically read off a shared
-     * contact card) and route into either an immediate message or a contact
-     * request. Never reads `card.accessLevel` — that snapshot is stale by the
-     * time an LLM acts on it. Instead defers to `resolveAdmission` so the
-     * answer reflects the target's *current* inbound policy.
+     * Message an existing Canon conversation or start/continue a direct one.
+     * Policy and admission are enforced by Canon; this method deliberately
+     * exposes no runtime configuration or trusted source-context fields.
      */
-    async reachOut(card, options) {
-        const target = {
-            targetUserId: card.userId,
-            ...(card.userType === 'ai_agent' && card.canonContactId
-                ? { canonContactId: card.canonContactId }
-                : {}),
-        };
-        const targetKey = target.canonContactId ?? target.targetUserId;
-        // Include the opener/request payloads in the dedupe key so two concurrent
-        // calls with different `text`, `requestMessage`, or setup choices don't silently collapse
-        // and lose the second caller's intended side effect.
-        const contextualKey = options?.selfContext
-            ? `${options.sourceConversationId ?? ''}\u0000${options.selfContext.type}\u0000${options.selfContext.context}`
-            : '';
-        const inFlightKey = `${targetKey}\u0000${options?.text ?? ''}\u0000${options?.requestMessage ?? ''}\u0000${JSON.stringify(options?.sessionConfig ?? null)}\u0000${JSON.stringify(options?.sessionSelection ?? null)}\u0000${contextualKey}`;
-        const inFlight = this.reachOutInFlight.get(inFlightKey);
-        if (inFlight)
-            return inFlight;
-        const promise = this.executeReachOut(target, options).finally(() => {
-            this.reachOutInFlight.delete(inFlightKey);
-        });
-        this.reachOutInFlight.set(inFlightKey, promise);
-        return promise;
-    }
-    async executeReachOut(target, options) {
-        const { targetUserId } = target;
-        if (options?.selfContext) {
-            if (!options.sourceConversationId) {
-                throw new Error('sourceConversationId is required for contextual reachOut');
-            }
-            if (!options.text) {
-                throw new Error('text is required for contextual reachOut');
-            }
-            const result = await this.apiClient.sendContextualMessage({
-                sourceConversationId: options.sourceConversationId,
-                targetUserId,
-                text: options.text,
-                selfContext: options.selfContext,
-                requestMessage: options.requestMessage ?? null,
-                sessionConfig: options.sessionConfig ?? null,
-                sessionSelection: options.sessionSelection,
-            });
-            return result.status === 'messaged'
-                ? {
-                    status: 'messaged',
-                    conversationId: result.conversationId,
-                    messageId: result.messageId,
-                    selfContextId: result.selfContextId,
-                    created: result.created,
-                    reused: result.reused,
-                    sessionSelection: result.sessionSelection,
-                }
-                : result;
-        }
-        return reachOutToCanonContact(this.apiClient, {
-            ...(target.canonContactId
-                ? { canonContactId: target.canonContactId }
-                : { targetUserId }),
-            text: options?.text ?? null,
-            requestMessage: options?.requestMessage ?? null,
-            sessionConfig: options?.sessionConfig ?? null,
-            sessionSelection: options?.sessionSelection,
-        });
+    async communicate(input) {
+        return this.apiClient.communicate(input);
     }
     async start() {
         if (this.running)
@@ -702,7 +598,6 @@ 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');
@@ -749,9 +644,6 @@ 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);
             },
@@ -781,26 +673,18 @@ 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;
         await rtm.start();
     }
-    async createConversation(options) {
-        return this.apiClient.createConversation(options);
+    async createGroup(options) {
+        return this.apiClient.createGroup(options);
     }
     // ── Calls ────────────────────────────────────────────────────────────
     // These return the LiveKit room token payload; the agent brings its own
@@ -869,37 +753,6 @@ 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;
@@ -1016,13 +869,6 @@ 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),
@@ -1631,9 +1477,6 @@ 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'
@@ -1642,9 +1485,6 @@ 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,
@@ -1708,6 +1548,7 @@ export class CanonAgent {
                 ownerName: '',
                 discoverable: false,
                 inboundPolicy: 'approval-required',
+                outboundPolicy: 'approval-required',
                 groupJoinPolicy: 'approval-required',
             };
             const provenance = latestMessage
@@ -1797,58 +1638,7 @@ export class CanonAgent {
             const react = (messageId, emoji) => this.apiClient.react(conversationId, messageId, emoji);
             const addMember = (userId) => this.apiClient.addMember(conversationId, userId);
             const removeMember = (userId) => this.apiClient.removeMember(conversationId, userId);
-            const sendContextualMessage = (target, text, options) => this.apiClient.sendContextualMessage({
-                sourceConversationId: conversationId,
-                ...target,
-                text,
-                ...options,
-                messageOptions: {
-                    ...(options.messageOptions ?? {}),
-                    metadata: {
-                        ...(options.messageOptions?.metadata ?? {}),
-                        turnId,
-                        turnSemantics: 'turn_complete',
-                    },
-                },
-            });
-            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 communicate = (input) => this.communicate(input);
             const requestApproval = async (request) => {
                 throwIfAborted();
                 const manager = this.ensureApprovalManager(agent);
@@ -2209,7 +1999,6 @@ export class CanonAgent {
                 messages: hydratedMessages,
                 history,
                 replyContext,
-                contactLifecycleEvents,
                 conversationId,
                 conversation,
                 ...(groupContext ? { groupContext } : {}),
@@ -2221,8 +2010,7 @@ export class CanonAgent {
                 react,
                 addMember,
                 removeMember,
-                sendContextualMessage,
-                reachOut,
+                communicate,
                 agent,
                 activeSelfContextId,
                 selfContexts,

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, 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';
+export type { AgentContext, CanonGroupContext, CanonKnownRecentParticipant, CanonMembershipChange, CanonContactRequest, GroupInviteRequirements, CanonMessage, CanonConversation, CommunicateInput, CommunicateResult, DirectConversationSelection, CanonConversationsPage, CanonConversationsPageOptions, CanonReplyContext, CanonSelfContext, CanonTurnContextV2, CanonRuntimeDescriptor, MessageUpdatedPayload, SendMessageOptions, CreateGroupOptions, CreateGroupResult, TurnVerbosity, TurnVerbosityConfig, } from '@canonmsg/core';
+export type { CanonAgentConnectionOptions, CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, ContactRequestHandler, FinalMessageResult, MessageHandler, MessageHandlerContext, MessageUpdatedHandler, ParticipationSuppressedHandler, ProgressMessageOptions, ProgressMessageResult, 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 ContactRequestUpdatedPayload, type ConversationUpdatedPayload, type MessageUpdatedPayload, type ParticipationSuppressedPayload, type VoiceSessionEventPayload } from '@canonmsg/core';
+import { type AgentContext, type ContactAddedPayload, type ContactApprovedPayload, type ContactRemovedPayload, type ContactRequestPayload, 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,7 +16,6 @@ export declare class RealtimeManager {
     private suppressedSseErrorCount;
     private onAgentContext;
     private onContactRequest;
-    private onContactRequestUpdated;
     private onContactApproved;
     private onContactAdded;
     private onContactRemoved;
@@ -26,7 +25,6 @@ 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?: {
@@ -39,7 +37,6 @@ 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: {
@@ -61,7 +58,6 @@ export declare class RealtimeManager {
     setConnectionHandlers(handlers: {
         onConnected?: () => void;
         onDisconnected?: () => void;
-        onReplayExpired?: () => void;
     }): void;
     setCallHandlers(handlers: {
         onCallStarted?: (payload: VoiceSessionEventPayload) => void;

package/dist/realtime.js

@@ -17,7 +17,6 @@ export class RealtimeManager {
     suppressedSseErrorCount = 0;
     onAgentContext = null;
     onContactRequest = null;
-    onContactRequestUpdated = null;
     onContactApproved = null;
     onContactAdded = null;
     onContactRemoved = null;
@@ -27,7 +26,6 @@ export class RealtimeManager {
     onMessageDeleted = null;
     onConnected = null;
     onDisconnected = null;
-    onReplayExpired = null;
     onCallStarted = null;
     onCallEnded = null;
     constructor(apiKey, debouncer, agentId, streamUrl, options) {
@@ -104,9 +102,6 @@ export class RealtimeManager {
                 onContactRequest: (payload) => {
                     this.onContactRequest?.(payload);
                 },
-                onContactRequestUpdated: (payload) => {
-                    this.onContactRequestUpdated?.(payload);
-                },
                 onContactApproved: (payload) => {
                     this.onContactApproved?.(payload);
                 },
@@ -130,7 +125,6 @@ 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);
@@ -181,7 +175,6 @@ export class RealtimeManager {
     }
     setContactRequestHandlers(handlers) {
         this.onContactRequest = handlers.onContactRequest ?? null;
-        this.onContactRequestUpdated = handlers.onContactRequestUpdated ?? null;
         this.onContactApproved = handlers.onContactApproved ?? null;
     }
     setContactGraphHandlers(handlers) {
@@ -208,7 +201,6 @@ 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,5 +1,5 @@
-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';
+export type { AddMemberResult, GroupInviteRequirements, AgentClientType, CanonGroupContext, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeDescriptor, CanonRuntimeFact, CanonRuntimeFactGroup, CanonRuntimePrimitiveId, CanonRuntimeProvenance, CanonTurnContextV2, CanonMessage, CanonConversation, CommunicateInput, CommunicateResult, CanonReplyContext, CanonContact, CanonContactRequest, CanonResolveAdmissionResult, ContactAddedPayload, ContactRemovedPayload, ContactSource, AgentContext, ResolveAdmissionTargetInput, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonSelfContext, CreateGroupOptions, CreateGroupResult, SendMessageOptions, SessionConfig, 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, CommunicateInput, CommunicateResult, CanonReplyContext, CanonRuntimeActionDispatch, CanonRuntimePrimitiveId, CanonRuntimeProvenance, CanonTurnContextV2, ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalResult, ApprovalRisk, RuntimeInputChoice, RuntimeInputAnswers, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, RuntimeCardNativeMetadata, RuntimeCardV1, ResumableMediaUploadResult, SendMessageOptions, TurnOutputBlock, TurnOutputBlockInput } from '@canonmsg/core';
 import type { MaterializeMediaOptions, MaterializedCanonAttachment, ReplyWithFileOptions, UploadMediaFileOptions } from './media.js';
 export interface ProgressMessageOptions extends SendMessageOptions {
     /**
@@ -152,8 +152,6 @@ 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. */
@@ -178,14 +176,8 @@ export interface MessageHandlerContext {
     addMember: (userId: string) => Promise<AddMemberResult>;
     /** Remove a member from this conversation (requires owner/admin role) */
     removeMember: (userId: string) => Promise<void>;
-    /** Send into another Canon conversation with private cross-session self-context. */
-    sendContextualMessage: (target: {
-        targetConversationId: string;
-    } | {
-        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>;
+    /** Message an existing Canon conversation or start/continue a direct one. */
+    communicate: (input: CommunicateInput) => Promise<CommunicateResult>;
     /** Trusted agent identity & access context */
     agent: import('@canonmsg/core').AgentContext;
     /** Active private self-context to continue for this turn, if Canon supplied one. */
@@ -312,15 +304,6 @@ 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. */
@@ -347,15 +330,6 @@ 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>;
 /**
@@ -365,56 +339,3 @@ export type ContactRemovedHandler = (payload: import('@canonmsg/core').ContactRe
  * benched agent can tell deliberate participation policy from a dead stream.
  */
 export type ParticipationSuppressedHandler = (payload: import('@canonmsg/core').ParticipationSuppressedPayload) => void | Promise<void>;
-/**
- * Result of `agent.reachOut(card)` — describes which side-effect ran so the
- * caller can decide what to tell the LLM. `messaged` means the agent opened
- * (or sent into) a direct conversation; `requested` means the target's
- * inbound policy required a contact request, which has been created;
- * `pending` means a prior outbound request is still awaiting approval; and
- * `blocked` / `unavailable` describe terminal states with `reason` set.
- */
-export type ReachOutResult = {
-    status: 'messaged';
-    conversationId: string;
-    messageId?: string;
-    selfContextId?: string;
-    created?: boolean;
-    reused?: boolean;
-    sessionSelection?: DirectSessionSelection['mode'];
-} | {
-    status: 'requested';
-    requestId: string | null;
-    deferredIntentId?: string | null;
-} | {
-    status: 'pending';
-    requestId: string | null;
-    deferredIntentId?: string | null;
-} | {
-    status: 'setup_required';
-    reason: string;
-} | {
-    status: 'no_session';
-    reason: string;
-} | {
-    status: 'blocked' | 'unavailable';
-    reason: string;
-};
-export interface ReachOutOptions {
-    /**
-     * Optional first message; sent now when allowed or parked for exact delivery
-     * after approval when it is visible text <= 4 KiB. Attachments and hidden
-     * session setup cannot be parked; a setup-requiring coding target returns
-     * `setup_required` before a contact request is created.
-     */
-    text?: string;
-    /** Optional contact-request note. Defaults to `text` when admission is `request-required`. */
-    requestMessage?: string;
-    /** Explicit session setup to use when the contact-card target is an agent. */
-    sessionConfig?: VerbSessionConfig | null;
-    /** Whether to continue an existing direct agent session or start a fresh one. */
-    sessionSelection?: DirectSessionSelection;
-    /** Source conversation for contextual cross-session reach-outs. */
-    sourceConversationId?: string;
-    /** Private context for the agent when this reach-out sends a cross-session message. */
-    selfContext?: SendContextualSelfContextInput;
-}

package/package.json

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