@canonmsg/agent-sdk 8.3.0 → 8.5.0

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, ReachOutOptions, ReachOutResult, ContactRequestHandler, RuntimeSignalHandler, RuntimePrimitiveHandler } from './types.js';
+import type { CanonAgentConnectionOptions, CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, CreateConversationOptions, MessageHandler, MessageUpdatedHandler, ParticipationSuppressedHandler, ReachOutOptions, ReachOutResult, 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
@@ -46,6 +46,7 @@ export declare class CanonAgent {
     private contactAddedHandler;
     private contactRemovedHandler;
     private messageUpdatedHandler;
+    private participationSuppressedHandler;
     private interruptHandler;
     private stopAndDropHandler;
     private newSessionHandler;
@@ -106,6 +107,15 @@ export declare class CanonAgent {
     on(event: 'contactApproved', handler: ContactRequestHandler): void;
     on(event: 'contactAdded', handler: ContactAddedHandler): void;
     on(event: 'contactRemoved', handler: ContactRemovedHandler): void;
+    /**
+     * OBSERVE-ONLY. Fires when the participation gate suppressed a turn this
+     * agent would otherwise have been dispatched (cap reached, mention required,
+     * agent-to-agent disabled). Never run a turn off this event — the withheld
+     * message is deliberately not delivered, and replying to it would defeat the
+     * loop protection. It exists so a benched agent can tell deliberate
+     * participation policy from a dead stream.
+     */
+    on(event: 'participationSuppressed', handler: ParticipationSuppressedHandler): void;
     on(event: 'interrupt', handler: RuntimeSignalHandler): void;
     on(event: 'stopAndDrop', handler: RuntimeSignalHandler): void;
     on(event: 'newSession', handler: RuntimeSignalHandler): void;
@@ -146,9 +156,9 @@ 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 }` — the target requires approval; the
-     *   server created a contact-request (kind: 'group_invite') routed to the
-     *   approver. The actual group join happens when that request is approved
+     * - `{ 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).
      *
      * Throws `CanonApiError` for hard failures (block, inactive, owner-only,
@@ -162,6 +172,7 @@ export declare class CanonAgent {
     }>;
     private handleContactRequestEvent;
     private handleContactGraphEvent;
+    private handleParticipationSuppressedEvent;
     private handleMessageUpdatedEvent;
     stop(): Promise<void>;
     private hasInterruptSupport;

package/dist/canon-agent.js

@@ -259,6 +259,7 @@ export class CanonAgent {
     contactAddedHandler = null;
     contactRemovedHandler = null;
     messageUpdatedHandler = null;
+    participationSuppressedHandler = null;
     interruptHandler = null;
     stopAndDropHandler = null;
     newSessionHandler = null;
@@ -470,6 +471,10 @@ export class CanonAgent {
             this.contactAddedHandler = handler;
             return;
         }
+        if (event === 'participationSuppressed') {
+            this.participationSuppressedHandler = handler;
+            return;
+        }
         if (event === 'interrupt') {
             this.interruptHandler = handler;
             if (this.running) {
@@ -719,6 +724,11 @@ export class CanonAgent {
         rtm.setConversationUpdatedHandler((payload) => {
             this.handleConversationUpdated(payload);
         });
+        rtm.setParticipationSuppressedHandler((payload) => {
+            // Observe-only by construction: this path never touches the debouncer,
+            // the message handler, or the turn pipeline.
+            void this.handleParticipationSuppressedEvent(payload);
+        });
         rtm.setMessageUpdatedHandler((payload) => {
             void this.handleMessageUpdatedEvent(payload);
         });
@@ -781,9 +791,9 @@ export class CanonAgent {
      * Outcome depends on the target's `groupJoinPolicy` and the relationship
      * graph:
      * - `{ status: 'added' }` — the member was added immediately.
-     * - `{ status: 'pending', requestId }` — the target requires approval; the
-     *   server created a contact-request (kind: 'group_invite') routed to the
-     *   approver. The actual group join happens when that request is approved
+     * - `{ 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).
      *
      * Throws `CanonApiError` for hard failures (block, inactive, owner-only,
@@ -818,6 +828,16 @@ export class CanonAgent {
             console.error('[canon-sdk] Contact-graph handler failed:', error instanceof Error ? error.message : error);
         }
     }
+    async handleParticipationSuppressedEvent(payload) {
+        if (!this.participationSuppressedHandler)
+            return;
+        try {
+            await this.participationSuppressedHandler(payload);
+        }
+        catch (error) {
+            console.error('[canon-sdk] participationSuppressed handler failed:', error instanceof Error ? error.message : error);
+        }
+    }
     async handleMessageUpdatedEvent(payload) {
         if (!this.messageUpdatedHandler)
             return;

package/dist/index.d.ts

@@ -1,11 +1,11 @@
 export { CanonAgent } from './canon-agent.js';
 export type { AgentContactsAPI, AgentConversationsAPI, AgentUsersAPI } from './canon-agent.js';
 export { ApprovalManager, buildApprovalOutcome, buildApprovalReply, buildApprovalRequest, CanonApiError, DEFAULT_APPROVAL_CONFIG, generateApprovalId, HOST_ADMISSION_ACTION_CAPABILITIES, HOST_ADMISSION_ACTIONS_DISABLED, parseApprovalReplyMetadata, parseApprovalRequestMetadata, parseSessionRule, redactSecrets, } from '@canonmsg/core';
-export type { ApprovalConfig, ApprovalNativeRequestMetadata, ApprovalOutcomeMetadata, ApprovalReplyMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalResult, ApprovalRisk, CanonContact, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeTurnModeActivation, CanonRuntimeTurnModeDescriptor, CanonRuntimeTurnModeScope, CanonRuntimeFact, CanonRuntimeFactGroup, CanonResolveAdmissionResult, ContactAddedPayload, ContactCardPayload, ContactRemovedPayload, ContactSource, HostAdmissionActionCapabilities, ResolveAdmissionTargetInput, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, RuntimeInputAnswers, RuntimeInputChoice, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, SessionRule, } from '@canonmsg/core';
+export type { ApprovalConfig, ApprovalNativeRequestMetadata, ApprovalOutcomeMetadata, ApprovalReplyMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalResult, ApprovalRisk, CanonContact, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeTurnModeActivation, CanonRuntimeTurnModeDescriptor, CanonRuntimeTurnModeScope, CanonRuntimeFact, CanonRuntimeFactGroup, CanonResolveAdmissionResult, ContactAddedPayload, ContactCardPayload, ContactRemovedPayload, ContactSource, HostAdmissionActionCapabilities, ParticipationSuppressedPayload, ResolveAdmissionTargetInput, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, RuntimeInputAnswers, RuntimeInputChoice, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, SessionRule, } from '@canonmsg/core';
 export { SessionManager } from './session-manager.js';
 export { DEFAULT_MEDIA_CACHE_DIR, getCodexImagePath, getMessageAttachments, inferUploadMimeType, isAnthropicImageAttachment, materializeAttachment, materializeMessageMedia, materializeReplyContextMedia, resolveAttachmentMimeType, sendMediaFileMessage, toAnthropicImageBlock, uploadMediaFile, } from './media.js';
 export type { AnthropicImageBlock, 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, 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, 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, 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';

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-export type { AddMemberResult, 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, SessionRule, ApprovalResult, } from '@canonmsg/core';
+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, 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, SendMessageOptions, SendContextualSelfContextInput, VerbSessionConfig, DirectSessionSelection, TurnOutputBlock, TurnOutputBlockInput } from '@canonmsg/core';
 import type { MaterializeMediaOptions, MaterializedCanonAttachment, ReplyWithFileOptions, UploadMediaFileOptions } from './media.js';
 export interface ProgressMessageOptions extends SendMessageOptions {
@@ -339,6 +339,13 @@ export interface CanonAgentOptions extends CanonAgentConnectionOptions {
 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>;
+/**
+ * Observe-only notice that the participation gate suppressed a turn this
+ * agent would otherwise have been dispatched (cap reached, mention required,
+ * agent-to-agent disabled). Never run a turn off this event — it exists so a
+ * 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-sdk",
-  "version": "8.3.0",
+  "version": "8.5.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.2.0"
+    "@canonmsg/core": "^10.3.0"
   },
   "publishConfig": {
     "access": "public"