@canonmsg/agent-sdk 3.0.0 → 3.1.1

package/dist/canon-agent.d.ts

@@ -1,4 +1,4 @@
-import { type AddMemberResult, type CanonContact, type CanonRuntimeActivityItem, type CanonRuntimeCommandDescriptor, type CanonRuntimeFact, type CanonRuntimePrimitiveId, type ContactCardPayload, type ClearRuntimeActivityOptions, type CreateContactRequestResult } from '@canonmsg/core';
+import { type AddMemberResult, type CanonContact, type CanonConversation, type CreateConversationResult, type CanonRuntimeActivityItem, type CanonRuntimeCommandDescriptor, type CanonRuntimeFact, type CanonRuntimePrimitiveId, type ContactCardPayload, type ClearRuntimeActivityOptions, type CreateContactRequestResult } from '@canonmsg/core';
 import type { CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, CreateConversationOptions, MessageHandler, MessageUpdatedHandler, ReachOutOptions, ReachOutResult, ContactRequestHandler, RuntimeSignalHandler, RuntimePrimitiveHandler } from './types.js';
 /**
  * Contact-graph operations exposed under `agent.contacts`. Wraps the REST
@@ -18,6 +18,11 @@ export interface AgentUsersAPI {
     block(userId: string): Promise<void>;
     unblock(userId: string): Promise<void>;
 }
+export interface AgentConversationsAPI {
+    list(options?: {
+        targetUserId?: string;
+    }): Promise<CanonConversation[]>;
+}
 export declare class CanonAgent {
     private options;
     private apiClient;
@@ -40,6 +45,8 @@ export declare class CanonAgent {
     readonly contacts: AgentContactsAPI;
     /** Block/unblock operations (`agent.users.*`). Initialized in the constructor. */
     readonly users: AgentUsersAPI;
+    /** Conversation discovery for choosing existing sessions intentionally. */
+    readonly conversations: AgentConversationsAPI;
     private readonly reachOutInFlight;
     private agentId;
     private agentContext;
@@ -85,9 +92,7 @@ export declare class CanonAgent {
     reachOut(card: ContactCardPayload, options?: ReachOutOptions): Promise<ReachOutResult>;
     private executeReachOut;
     start(): Promise<void>;
-    createConversation(options: CreateConversationOptions): Promise<{
-        conversationId: string;
-    }>;
+    createConversation(options: CreateConversationOptions): Promise<CreateConversationResult>;
     updateTopic(conversationId: string, topic: string): Promise<void>;
     leaveConversation(conversationId: string): Promise<void>;
     updateConversationName(conversationId: string, name: string): Promise<void>;

package/dist/canon-agent.js

@@ -245,6 +245,8 @@ export class CanonAgent {
     contacts;
     /** Block/unblock operations (`agent.users.*`). Initialized in the constructor. */
     users;
+    /** Conversation discovery for choosing existing sessions intentionally. */
+    conversations;
     reachOutInFlight = new Map();
     agentId = null;
     agentContext = null;
@@ -292,6 +294,14 @@ export class CanonAgent {
             block: (userId) => apiClient.blockUser(userId),
             unblock: (userId) => apiClient.unblockUser(userId),
         };
+        this.conversations = {
+            list: async (options = {}) => {
+                const conversations = await apiClient.getConversations();
+                if (!options.targetUserId)
+                    return conversations;
+                return conversations.filter((conversation) => conversation.memberIds.includes(options.targetUserId));
+            },
+        };
         if (options.sessions?.enabled) {
             this.sessionManager = new SessionManager({
                 contextLimit: options.sessions.contextLimit,
@@ -457,7 +467,7 @@ export class CanonAgent {
         const contextualKey = options?.selfContext
             ? `${options.sourceConversationId ?? ''}\u0000${options.selfContext.type}\u0000${options.selfContext.context}`
             : '';
-        const inFlightKey = `${targetUserId}\u0000${options?.text ?? ''}\u0000${options?.requestMessage ?? ''}\u0000${JSON.stringify(options?.sessionConfig ?? null)}\u0000${contextualKey}`;
+        const inFlightKey = `${targetUserId}\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;
@@ -482,6 +492,7 @@ export class CanonAgent {
                 selfContext: options.selfContext,
                 requestMessage: options.requestMessage ?? null,
                 sessionConfig: options.sessionConfig ?? null,
+                sessionSelection: options.sessionSelection,
             });
             return result.status === 'messaged'
                 ? {
@@ -489,6 +500,9 @@ export class CanonAgent {
                     conversationId: result.conversationId,
                     messageId: result.messageId,
                     selfContextId: result.selfContextId,
+                    created: result.created,
+                    reused: result.reused,
+                    sessionSelection: result.sessionSelection,
                 }
                 : result;
         }
@@ -497,6 +511,7 @@ export class CanonAgent {
             text: options?.text ?? null,
             requestMessage: options?.requestMessage ?? null,
             sessionConfig: options?.sessionConfig ?? null,
+            sessionSelection: options?.sessionSelection,
         });
     }
     async start() {
@@ -1363,6 +1378,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 +1862,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 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, 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, CreateConversationResult, DirectSessionSelection, } 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

@@ -1,5 +1,5 @@
-export type { AddMemberResult, AgentClientType, CanonGroupContext, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeDescriptor, CanonRuntimeFact, CanonRuntimeFactGroup, CanonRuntimePrimitiveId, CanonRuntimeProvenance, CanonTurnContextV2, CanonMessage, CanonConversation, CanonReplyContext, CanonContact, CanonContactRequest, CanonResolveAdmissionResult, ContactAddedPayload, ContactRemovedPayload, ContactSource, AgentContext, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonSelfContext, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, SessionConfig, 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, SessionConfig, TurnOutputBlock, TurnOutputBlockInput } from '@canonmsg/core';
+export type { AddMemberResult, AgentClientType, CanonGroupContext, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeDescriptor, CanonRuntimeFact, CanonRuntimeFactGroup, CanonRuntimePrimitiveId, CanonRuntimeProvenance, CanonTurnContextV2, CanonMessage, CanonConversation, CanonReplyContext, CanonContact, CanonContactRequest, CanonResolveAdmissionResult, ContactAddedPayload, ContactRemovedPayload, ContactSource, AgentContext, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonSelfContext, CreateConversationResult, DirectSessionSelection, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, SessionConfig, 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, SessionConfig, DirectSessionSelection, TurnOutputBlock, TurnOutputBlockInput } from '@canonmsg/core';
 import type { MaterializeMediaOptions, MaterializedCanonAttachment, ReplyWithFileOptions, UploadMediaFileOptions } from './media.js';
 export interface ProgressMessageOptions extends SendMessageOptions {
     /**
@@ -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
@@ -280,6 +282,9 @@ export type ReachOutResult = {
     conversationId: string;
     messageId?: string;
     selfContextId?: string;
+    created?: boolean;
+    reused?: boolean;
+    sessionSelection?: DirectSessionSelection['mode'];
 } | {
     status: 'requested';
     requestId: string | null;
@@ -291,6 +296,9 @@ export type ReachOutResult = {
 } | {
     status: 'setup_required';
     reason: string;
+} | {
+    status: 'no_session';
+    reason: string;
 } | {
     status: 'blocked' | 'unavailable';
     reason: string;
@@ -302,6 +310,8 @@ export interface ReachOutOptions {
     requestMessage?: string;
     /** Explicit session setup to use when the contact-card target is an agent. */
     sessionConfig?: SessionConfig | 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. */

package/package.json

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