@canonmsg/agent-sdk 3.0.0 → 3.1.0

package/dist/canon-agent.js

@@ -1363,6 +1363,9 @@ export class CanonAgent {
                 replyContext,
                 message: latestMessage ?? undefined,
             });
+            const requestedTurnMode = latestMessage
+                ? normalizeTurnMetadata(latestMessage.metadata)?.requestedTurnMode ?? null
+                : null;
             // Build context methods bound to this conversation
             const deleteMessage = (messageId) => this.apiClient.deleteMessage(conversationId, messageId);
             const markAsRead = () => this.apiClient.markAsRead(conversationId);
@@ -1844,6 +1847,7 @@ export class CanonAgent {
                 selfContexts,
                 provenance,
                 turnContext,
+                requestedTurnMode,
                 requestApproval,
                 requestRuntimeInput,
                 requestCard,

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 export { CanonAgent } from './canon-agent.js';
 export type { AgentContactsAPI, 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, CanonRuntimeFact, CanonRuntimeFactGroup, CanonResolveAdmissionResult, ContactAddedPayload, ContactCardPayload, ContactRemovedPayload, ContactSource, HostAdmissionActionCapabilities, 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, 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 { AgentContext, CanonGroupContext, CanonKnownRecentParticipant, CanonMembershipChange, CanonContactRequest, CanonMessage, CanonConversation, CanonReplyContext, CanonSelfContext, CanonTurnContextV2, MessageUpdatedPayload, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, CreateConversationOptions, } from '@canonmsg/core';
+export type { AgentContext, CanonGroupContext, CanonKnownRecentParticipant, CanonMembershipChange, CanonContactRequest, CanonMessage, CanonConversation, CanonReplyContext, CanonSelfContext, CanonTurnContextV2, CanonRuntimeDescriptor, MessageUpdatedPayload, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, CreateConversationOptions, } from '@canonmsg/core';
 export type { CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, ContactRequestHandler, MessageHandler, MessageHandlerContext, MessageUpdatedHandler, ProgressMessageOptions, ProgressMessageResult, ReachOutOptions, ReachOutResult, RuntimeApprovalRequest, RuntimeInputRequest, RuntimeInputResult, RuntimeControlSurface, RuntimePrimitiveContext, RuntimePrimitiveHandler, RuntimePrimitiveHandlers, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';

package/dist/realtime.js

@@ -32,6 +32,10 @@ export class RealtimeManager {
             streamUrl,
             handler: {
                 onMessage: (payload) => {
+                    if (payload.turnDispatch && payload.turnDispatch.kind !== 'run_turn') {
+                        console.error(`[canon-sdk] Ignoring server-dispatched observe-only message in ${payload.conversationId}: ${payload.turnDispatch.reason}`);
+                        return;
+                    }
                     const m = payload.message;
                     const message = {
                         id: m.id,

package/dist/turn-filter.d.ts

@@ -1,8 +1,9 @@
-import { type ResolvedAgentBehaviorPolicy, type CanonMessage } from '@canonmsg/core';
+import { type ResolvedAgentBehaviorPolicy, type CanonMessage, type MessageCreatedPayload } from '@canonmsg/core';
 export declare function shouldDispatchInboundMessage(_conversationId: string, agentId: string, message: CanonMessage, options?: {
     conversationType?: 'direct' | 'group' | 'unknown';
     behavior?: ResolvedAgentBehaviorPolicy | null;
     recentHumanCount?: number;
     consecutiveAgentTurns?: number;
     currentAgentStreakStartedByHuman?: boolean;
+    turnDispatch?: MessageCreatedPayload['turnDispatch'];
 }): Promise<boolean>;

package/dist/turn-filter.js

@@ -2,6 +2,9 @@ import { evaluateParticipationPolicy, shouldTriggerAgentTurn, } from '@canonmsg/
 export async function shouldDispatchInboundMessage(_conversationId, agentId, message, options) {
     if (message.senderId === agentId)
         return false;
+    if (options?.turnDispatch) {
+        return options.turnDispatch.kind === 'run_turn';
+    }
     const triggerDecision = shouldTriggerAgentTurn({
         senderType: message.senderType,
         metadata: message.metadata,

package/dist/types.d.ts

@@ -150,6 +150,8 @@ export interface MessageHandlerContext {
     provenance: CanonRuntimeProvenance;
     /** Compact structured Canon turn context for the latest inbound message in this handler batch. */
     turnContext: CanonTurnContextV2;
+    /** Runtime turn mode requested by the sender for this inbound turn, if any. */
+    requestedTurnMode: string | null;
     /**
      * Ask the conversation owner to approve a native runtime action. This only
      * renders Canon's inline approval card; runtimes must explicitly wait for

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-sdk",
-  "version": "3.0.0",
+  "version": "3.1.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": "^2.0.0"
+    "@canonmsg/core": "^2.1.0"
   },
   "publishConfig": {
     "access": "public"