@canonmsg/agent-sdk 8.8.0 → 9.0.0

package/README.md

@@ -190,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 |
@@ -508,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.
 
@@ -533,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 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 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,7 +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>;
 }
 /**
  * User-level moderation actions exposed under `agent.users`.
@@ -62,7 +61,6 @@ export declare class CanonAgent {
     readonly users: AgentUsersAPI;
     /** Conversation discovery for choosing existing sessions intentionally. */
     readonly conversations: AgentConversationsAPI;
-    private readonly reachOutInFlight;
     private agentId;
     private agentContext;
     private approvalManager;
@@ -127,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. */

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, 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';
@@ -275,7 +275,6 @@ export class CanonAgent {
     users;
     /** Conversation discovery for choosing existing sessions intentionally. */
     conversations;
-    reachOutInFlight = new Map();
     agentId = null;
     agentContext = null;
     approvalManager = null;
@@ -335,7 +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),
         };
         this.users = {
             block: (userId) => apiClient.blockUser(userId),
@@ -546,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)
@@ -748,8 +683,8 @@ export class CanonAgent {
         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
@@ -1613,6 +1548,7 @@ export class CanonAgent {
                 ownerName: '',
                 discoverable: false,
                 inboundPolicy: 'approval-required',
+                outboundPolicy: 'approval-required',
                 groupJoinPolicy: 'approval-required',
             };
             const provenance = latestMessage
@@ -1702,24 +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) => this.reachOut(card, {
-                ...(options ?? {}),
-                sourceConversationId: conversationId,
-            });
+            const communicate = (input) => this.communicate(input);
             const requestApproval = async (request) => {
                 throwIfAborted();
                 const manager = this.ensureApprovalManager(agent);
@@ -2091,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, 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, 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/types.d.ts

@@ -1,5 +1,5 @@
-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';
-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 {
     /**
@@ -176,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. */
@@ -345,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.8.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.6.0"
+    "@canonmsg/core": "^11.0.0"
   },
   "publishConfig": {
     "access": "public"