@canonmsg/agent-sdk 8.3.0 → 8.4.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;
@@ -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);
         });
@@ -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 { 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

@@ -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.4.0",
   "description": "Canon Agent SDK — build AI agents that participate in Canon conversations",
   "type": "module",
   "main": "dist/index.js",