@canonmsg/agent-sdk 9.1.0 → 10.0.0

package/README.md

@@ -190,7 +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 |
-| `communicate` | function | Message an existing conversation, start a direct conversation, create a group, or forward an exact message |
+| `communicate` | function | Message an existing conversation, start a direct conversation, create a group, forward an exact message, share a contact, or manage group members |
 | `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 |
@@ -213,16 +213,15 @@ Messages from the agent itself are automatically filtered out -- your handler on
 
 ## Events
 
-`agent.on(event, handler)` accepts eleven events. Each event holds a single handler; registering again replaces it.
+`agent.on(event, handler)` accepts ten events. Each event holds a single handler; registering again replaces it.
 
 | Event | Payload | Notes |
 |---|---|---|
 | `message` | `MessageHandlerContext` | Debounced inbound batch for one conversation |
 | `messageUpdated` | `MessageUpdatedPayload` | Reaction/status changes; not a new turn |
-| `contactRequest` | `CanonContactRequest` | Awareness only — the owner still approves |
-| `contactApproved` | `CanonContactRequest` | Awareness only |
 | `contactAdded` | `ContactAddedPayload` | A contact edge now exists |
 | `contactRemoved` | `ContactRemovedPayload` | A contact edge was removed |
+| `participationSuppressed` | `ParticipationSuppressedPayload` | Observe-only notice that policy withheld a turn |
 | `interrupt` | `RuntimeSignalContext` | Same signal as `runtimeControls.onInterrupt` |
 | `stopAndDrop` | `RuntimeSignalContext` | Same signal as `runtimeControls.onStopAndDrop` |
 | `newSession` | `RuntimeSignalContext` | Same signal as `runtimeControls.onNewSession` |
@@ -278,22 +277,6 @@ const review = await ctx.requestCard({
 
 The SDK does not validate card documents — it forwards `request.card` to Canon as-is, and a malformed card surfaces as a backend 400. Install [`@canonmsg/rich-cards`](https://www.npmjs.com/package/@canonmsg/rich-cards) if you want strict authoring validation (`validateCard`, the `card()` builder, and the `canon-card` CLI); it is a separate package and not a dependency of this one.
 
-## Contact Request Awareness
-
-Agents can also observe contact-request lifecycle events without becoming the approver:
-
-```typescript
-agent.on('contactRequest', (request) => {
-  console.log('New request aimed at this agent:', request.requesterName);
-});
-
-agent.on('contactApproved', (request) => {
-  console.log('Request approved:', request.id);
-});
-```
-
-These are awareness callbacks only. Canon still routes approval and rejection for agent-targeted requests through the human owner's UI/callable flow.
-
 ### Turn-aware example
 
 ```typescript

package/dist/canon-agent.d.ts

@@ -1,5 +1,5 @@
 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';
+import type { CanonAgentConnectionOptions, CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, MessageHandler, MessageUpdatedHandler, ParticipationSuppressedHandler, 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
@@ -40,8 +40,6 @@ export declare class CanonAgent {
     private realtimeManager;
     private sessionManager;
     private handler;
-    private contactRequestHandler;
-    private contactApprovedHandler;
     private contactAddedHandler;
     private contactRemovedHandler;
     private messageUpdatedHandler;
@@ -101,8 +99,6 @@ export declare class CanonAgent {
     private filterApprovalReplyMessages;
     on(event: 'message', handler: MessageHandler): void;
     on(event: 'messageUpdated', handler: MessageUpdatedHandler): void;
-    on(event: 'contactRequest', handler: ContactRequestHandler): void;
-    on(event: 'contactApproved', handler: ContactRequestHandler): void;
     on(event: 'contactAdded', handler: ContactAddedHandler): void;
     on(event: 'contactRemoved', handler: ContactRemovedHandler): void;
     /**
@@ -151,12 +147,11 @@ export declare class CanonAgent {
      * Outcome depends on the target's `groupJoinPolicy` and the relationship
      * graph:
      * - `{ status: 'added' }` — the member was added immediately.
-     * - `{ status: 'pending', requestId, requirements }` — the target needs
-     *   policy approval, owner session setup, or both. The server created one
-     *   `group_invite`; membership activates after every requirement is met
-     *   (you can listen for `contact.approved` SSE events to know when).
+     * - `{ status: 'pending', requestId }` — the target needs policy approval.
+     *   The server created one `group_invite`; membership activates after approval
+     *   The approved membership arrives through the normal conversation update.
      *
-     * Throws `CanonApiError` for hard failures (block, inactive, owner-only,
+     * Throws `CanonApiError` for hard failures (block, inactive, closed policy,
      * member cap, requester not authorized).
      */
     addMember(conversationId: string, userId: string): Promise<AddMemberResult>;
@@ -165,7 +160,6 @@ export declare class CanonAgent {
         url: string;
         attachment: import('@canonmsg/core').MediaAttachment;
     }>;
-    private handleContactRequestEvent;
     private handleContactGraphEvent;
     private handleParticipationSuppressedEvent;
     private handleMessageUpdatedEvent;

package/dist/canon-agent.js

@@ -281,8 +281,6 @@ export class CanonAgent {
     realtimeManager = null;
     sessionManager = null;
     handler = null;
-    contactRequestHandler = null;
-    contactApprovedHandler = null;
     contactAddedHandler = null;
     contactRemovedHandler = null;
     messageUpdatedHandler = null;
@@ -484,14 +482,6 @@ export class CanonAgent {
             this.messageUpdatedHandler = handler;
             return;
         }
-        if (event === 'contactRequest') {
-            this.contactRequestHandler = handler;
-            return;
-        }
-        if (event === 'contactApproved') {
-            this.contactApprovedHandler = handler;
-            return;
-        }
         if (event === 'contactAdded') {
             this.contactAddedHandler = handler;
             return;
@@ -634,7 +624,6 @@ export class CanonAgent {
             const runtimeState = this.createRuntimeStatePublisher();
             for (const id of this.cachedConversationIds) {
                 runtimeState?.writeSessionState(id, {
-                    cwd: process.cwd(),
                     isActive: true,
                     ...(this.options.clientType ? { clientType: this.options.clientType } : {}),
                 }).catch(() => { });
@@ -667,14 +656,6 @@ export class CanonAgent {
             this.agentContext = ctx;
             this.ensureApprovalManager(ctx);
         });
-        rtm.setContactRequestHandlers({
-            onContactRequest: (request) => {
-                void this.handleContactRequestEvent(this.contactRequestHandler, request);
-            },
-            onContactApproved: (request) => {
-                void this.handleContactRequestEvent(this.contactApprovedHandler, request);
-            },
-        });
         rtm.setContactGraphHandlers({
             onContactAdded: (payload) => {
                 void this.handleContactGraphEvent(this.contactAddedHandler, payload);
@@ -753,12 +734,11 @@ export class CanonAgent {
      * Outcome depends on the target's `groupJoinPolicy` and the relationship
      * graph:
      * - `{ status: 'added' }` — the member was added immediately.
-     * - `{ status: 'pending', requestId, requirements }` — the target needs
-     *   policy approval, owner session setup, or both. The server created one
-     *   `group_invite`; membership activates after every requirement is met
-     *   (you can listen for `contact.approved` SSE events to know when).
+     * - `{ status: 'pending', requestId }` — the target needs policy approval.
+     *   The server created one `group_invite`; membership activates after approval
+     *   The approved membership arrives through the normal conversation update.
      *
-     * Throws `CanonApiError` for hard failures (block, inactive, owner-only,
+     * Throws `CanonApiError` for hard failures (block, inactive, closed policy,
      * member cap, requester not authorized).
      */
     async addMember(conversationId, userId) {
@@ -770,16 +750,6 @@ export class CanonAgent {
     async uploadMedia(conversationId, data, mimeType, fileName) {
         return this.apiClient.uploadMedia(conversationId, data, mimeType, fileName);
     }
-    async handleContactRequestEvent(handler, request) {
-        if (!handler)
-            return;
-        try {
-            await handler(request);
-        }
-        catch (error) {
-            console.error('[canon-sdk] Contact-request handler failed:', error instanceof Error ? error.message : error);
-        }
-    }
     async handleContactGraphEvent(handler, payload) {
         if (!handler)
             return;
@@ -1246,6 +1216,7 @@ export class CanonAgent {
         // The freshest message in the batch is the turn's trigger — same convention
         // as the provenance lookup for turn verbosity below.
         const triggeringMessageId = messages[messages.length - 1]?.id;
+        const triggeringReplyAuthority = messages[messages.length - 1]?.replyAuthority;
         const agentId = this.agentId;
         const runtimeState = this.createRuntimeStatePublisher();
         const queueDepth = () => this.sessionManager?.getQueueDepth(conversationId) ?? 0;
@@ -1520,9 +1491,12 @@ export class CanonAgent {
             const activeSelfContextId = selfContexts.length > 0 ? resolvedActiveSelfContextId : null;
             const withActiveSelfContext = (options) => {
                 const base = { ...(options ?? {}) };
-                if (base.selfContextId !== undefined)
-                    return base;
-                return activeSelfContextId ? { ...base, selfContextId: activeSelfContextId } : base;
+                const withContext = base.selfContextId !== undefined || !activeSelfContextId
+                    ? base
+                    : { ...base, selfContextId: activeSelfContextId };
+                return withContext.replyAuthority !== undefined || !triggeringReplyAuthority
+                    ? withContext
+                    : { ...withContext, replyAuthority: triggeringReplyAuthority };
             };
             // Core's chunked sender walks the parts in a plain loop and knows nothing
             // about this turn's abort signal, so a stop landing after part 1 would

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, 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, RuntimePlanReviewRequest, RuntimePlanReviewResult, RuntimeControlSurface, RuntimePrimitiveContext, RuntimePrimitiveHandler, RuntimePrimitiveHandlers, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';
+export type { AgentContext, CanonGroupContext, CanonKnownRecentParticipant, CanonMembershipChange, 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, FinalMessageResult, MessageHandler, MessageHandlerContext, MessageUpdatedHandler, ParticipationSuppressedHandler, ProgressMessageOptions, ProgressMessageResult, RuntimeApprovalRequest, RuntimeInputRequest, RuntimeInputResult, RuntimePlanReviewRequest, RuntimePlanReviewResult, 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 ContactRemovedPayload, 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:
@@ -15,8 +15,6 @@ export declare class RealtimeManager {
     private lastSseErrorAt;
     private suppressedSseErrorCount;
     private onAgentContext;
-    private onContactRequest;
-    private onContactApproved;
     private onContactAdded;
     private onContactRemoved;
     private onConversationUpdated;
@@ -35,10 +33,6 @@ export declare class RealtimeManager {
     private pruneRecentInboundMessageIds;
     private logSseError;
     setOnAgentContext(cb: (ctx: AgentContext) => void): void;
-    setContactRequestHandlers(handlers: {
-        onContactRequest?: (payload: ContactRequestPayload) => void;
-        onContactApproved?: (payload: ContactApprovedPayload) => void;
-    }): void;
     setContactGraphHandlers(handlers: {
         onContactAdded?: (payload: ContactAddedPayload) => void;
         onContactRemoved?: (payload: ContactRemovedPayload) => void;

package/dist/realtime.js

@@ -16,8 +16,6 @@ export class RealtimeManager {
     lastSseErrorAt = 0;
     suppressedSseErrorCount = 0;
     onAgentContext = null;
-    onContactRequest = null;
-    onContactApproved = null;
     onContactAdded = null;
     onContactRemoved = null;
     onConversationUpdated = null;
@@ -86,6 +84,7 @@ export class RealtimeManager {
                         createdAt: m.createdAt ?? new Date().toISOString(),
                         ...(m.contactCard ? { contactCard: m.contactCard } : {}),
                         ...(m.metadata ? { metadata: m.metadata } : {}),
+                        ...(payload.replyAuthority ? { replyAuthority: payload.replyAuthority } : {}),
                     };
                     this.debouncer.add(payload.conversationId, message, payload.provenance ?? null);
                 },
@@ -99,12 +98,6 @@ export class RealtimeManager {
                 onAgentContext: (ctx) => {
                     this.onAgentContext?.(ctx);
                 },
-                onContactRequest: (payload) => {
-                    this.onContactRequest?.(payload);
-                },
-                onContactApproved: (payload) => {
-                    this.onContactApproved?.(payload);
-                },
                 onContactAdded: (payload) => {
                     this.onContactAdded?.(payload);
                 },
@@ -173,10 +166,6 @@ export class RealtimeManager {
     setOnAgentContext(cb) {
         this.onAgentContext = cb;
     }
-    setContactRequestHandlers(handlers) {
-        this.onContactRequest = handlers.onContactRequest ?? null;
-        this.onContactApproved = handlers.onContactApproved ?? null;
-    }
     setContactGraphHandlers(handlers) {
         this.onContactAdded = handlers.onContactAdded ?? null;
         this.onContactRemoved = handlers.onContactRemoved ?? 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, 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, RuntimePlanRequestPayload, RuntimePlanRequestResult, RuntimeCardNativeMetadata, RuntimeCardV1, ResumableMediaUploadResult, MediaAttachment, VideoProcessingStatus, VideoProcessingErrorCode, SessionRule, ApprovalResult, } from '@canonmsg/core';
+export type { AddMemberResult, AgentClientType, CanonGroupContext, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeDescriptor, CanonRuntimeFact, CanonRuntimeFactGroup, CanonRuntimePrimitiveId, CanonRuntimeProvenance, CanonTurnContextV2, CanonMessage, CanonConversation, CommunicateInput, CommunicateResult, CanonReplyContext, CanonContact, CanonResolveAdmissionResult, ContactAddedPayload, ContactRemovedPayload, ContactSource, AgentContext, ResolveAdmissionTargetInput, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonSelfContext, CreateGroupOptions, CreateGroupResult, SendMessageOptions, TurnLifecycleState, TurnOutputBlock, TurnOutputBlockInput, ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalRisk, ApprovalReplyMetadata, ApprovalOutcomeMetadata, RuntimeInputChoice, RuntimeInputAnswers, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, RuntimePlanRequestPayload, RuntimePlanRequestResult, 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, RuntimePlanRequestPayload, RuntimePlanRequestResult, RuntimeCardNativeMetadata, RuntimeCardV1, ResumableMediaUploadResult, SendMessageOptions, TurnOutputBlock, TurnOutputBlockInput } from '@canonmsg/core';
 import type { MaterializeMediaOptions, MaterializedCanonAttachment, ReplyWithFileOptions, UploadMediaFileOptions } from './media.js';
 export interface ProgressMessageOptions extends SendMessageOptions {
@@ -345,7 +345,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 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": "9.1.0",
+  "version": "10.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": "^11.0.0"
+    "@canonmsg/core": "^12.0.0"
   },
   "publishConfig": {
     "access": "public"