@canonmsg/agent-sdk 1.1.1 → 1.1.3

package/dist/canon-agent.js

@@ -1,4 +1,4 @@
-import { CanonClient, createRuntimeStatePublisher, FINAL_MESSAGE_HANDOFF_MS, initRTDBAuth, rtdbRead, rtdbWrite, mergeWorkSessionContexts, normalizeTurnMetadata, reachOutToCanonContact, } from '@canonmsg/core';
+import { CanonClient, createRuntimeStatePublisher, FINAL_MESSAGE_HANDOFF_MS, initRTDBAuth, rtdbRead, rtdbWrite, normalizeTurnMetadata, reachOutToCanonContact, } from '@canonmsg/core';
 import { randomUUID } from 'node:crypto';
 import { AuthManager } from './auth.js';
 import { Debouncer } from './debouncer.js';
@@ -150,9 +150,12 @@ export class CanonAgent {
     async reachOut(card, options) {
         const targetUserId = card.userId;
         // Include the opener/request payloads in the dedupe key so two concurrent
-        // calls with different `text` or `requestMessage` don't silently collapse
+        // calls with different `text`, `requestMessage`, or setup choices don't silently collapse
         // and lose the second caller's intended side effect.
-        const inFlightKey = `${targetUserId}\u0000${options?.text ?? ''}\u0000${options?.requestMessage ?? ''}`;
+        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 inFlight = this.reachOutInFlight.get(inFlightKey);
         if (inFlight)
             return inFlight;
@@ -163,10 +166,34 @@ export class CanonAgent {
         return promise;
     }
     async executeReachOut(targetUserId, options) {
+        if (options?.selfContext) {
+            if (!options.sourceConversationId) {
+                throw new Error('sourceConversationId is required for contextual reachOut');
+            }
+            if (!options.text) {
+                throw new Error('text is required for contextual reachOut');
+            }
+            const result = await this.apiClient.sendContextualMessage({
+                sourceConversationId: options.sourceConversationId,
+                targetUserId,
+                text: options.text,
+                selfContext: options.selfContext,
+                requestMessage: options.requestMessage ?? null,
+                sessionConfig: options.sessionConfig ?? null,
+            });
+            return result.status === 'messaged'
+                ? {
+                    status: 'messaged',
+                    conversationId: result.conversationId,
+                    messageId: result.messageId,
+                }
+                : result;
+        }
         return reachOutToCanonContact(this.apiClient, {
             targetUserId,
             text: options?.text ?? null,
             requestMessage: options?.requestMessage ?? null,
+            sessionConfig: options?.sessionConfig ?? null,
         });
     }
     async start() {
@@ -633,6 +660,9 @@ export class CanonAgent {
                 catch { }
                 const result = await this.apiClient.sendMessage(conversationId, text, {
                     ...(options ?? {}),
+                    ...(options?.selfContextId === undefined && activeSelfContextId
+                        ? { selfContextId: activeSelfContextId }
+                        : {}),
                     metadata: {
                         ...(options?.metadata ?? {}),
                         turnId,
@@ -671,11 +701,8 @@ export class CanonAgent {
                     m.isOwner = m.senderId === ownerId;
                 }
             }
-            const explicitWorkSession = messages.find((message) => message.workSession)?.workSession
-                ?? history.find((message) => message.workSession)?.workSession
-                ?? null;
-            const activeWorkSessions = mergeWorkSessionContexts(explicitWorkSession, page.workSessions ?? []);
-            const workSession = explicitWorkSession;
+            const selfContexts = page.selfContexts ?? [];
+            const activeSelfContextId = selfContexts[0]?.id;
             // Build agent context (fallback to minimal if not yet received)
             const agent = this.agentContext ?? {
                 agentId: this.agentId,
@@ -692,32 +719,21 @@ export class CanonAgent {
             const react = (messageId, emoji) => this.apiClient.react(conversationId, messageId, emoji);
             const addMember = (userId) => this.apiClient.addMember(conversationId, userId);
             const removeMember = (userId) => this.apiClient.removeMember(conversationId, userId);
-            const createWorkSession = (options) => this.apiClient.createWorkSession({
-                conversationId,
-                ...(options ?? {}),
-            });
-            const getWorkSession = (workSessionId, targetConversationId = conversationId) => this.apiClient.getWorkSession(workSessionId, targetConversationId);
-            const updateWorkSessionContext = (workSessionId, options) => this.apiClient.upsertWorkSessionConversation(workSessionId, conversationId, options);
-            const sendLinkedMessage = (targetConversationId, text, options) => {
-                if (!options?.workSessionId && !options?.createWorkSession) {
-                    throw new Error('sendLinkedMessage requires workSessionId or createWorkSession');
-                }
-                return this.apiClient.sendLinkedMessage({
-                    sourceConversationId: conversationId,
-                    targetConversationId,
-                    text,
-                    ...(options ?? {}),
-                    messageOptions: {
-                        ...(options?.messageOptions ?? {}),
-                        metadata: {
-                            ...(options?.messageOptions?.metadata ?? {}),
-                            turnId,
-                            turnSemantics: 'turn_complete',
-                            turnComplete: true,
-                        },
+            const sendContextualMessage = (target, text, options) => this.apiClient.sendContextualMessage({
+                sourceConversationId: conversationId,
+                ...target,
+                text,
+                ...options,
+                messageOptions: {
+                    ...(options.messageOptions ?? {}),
+                    metadata: {
+                        ...(options.messageOptions?.metadata ?? {}),
+                        turnId,
+                        turnSemantics: 'turn_complete',
+                        turnComplete: true,
                     },
-                });
-            };
+                },
+            });
             const uploadFile = (filePath, options) => uploadMediaFile(this.apiClient, conversationId, filePath, options);
             const replyWithFile = async (filePath, text = '', options) => {
                 try {
@@ -732,13 +748,15 @@ export class CanonAgent {
                             ? { replyToPosition: options.replyToPosition }
                             : {}),
                         ...(options?.mentions ? { mentions: options.mentions } : {}),
+                        ...(options?.selfContextId === undefined && activeSelfContextId
+                            ? { selfContextId: activeSelfContextId }
+                            : {}),
                         metadata: {
                             ...(options?.metadata ?? {}),
                             turnId,
                             turnSemantics: 'turn_complete',
                             turnComplete: true,
                         },
-                        ...(options?.workSessionId ? { workSessionId: options.workSessionId } : {}),
                         contentType: uploaded.attachment.kind,
                         attachments: [uploaded.attachment],
                     });
@@ -766,13 +784,9 @@ export class CanonAgent {
                 react,
                 addMember,
                 removeMember,
-                createWorkSession,
-                getWorkSession,
-                updateWorkSessionContext,
-                sendLinkedMessage,
+                sendContextualMessage,
                 agent,
-                workSession,
-                activeWorkSessions,
+                selfContexts,
                 abortSignal: abortController.signal,
                 media: {
                     materialize: (message = hydratedMessages[hydratedMessages.length - 1], options) => {

package/dist/index.d.ts

@@ -6,5 +6,5 @@ export { SessionManager } from './session-manager.js';
 export { getCodexImagePath, getMessageAttachments, inferUploadMimeType, isAnthropicImageAttachment, materializeAttachment, materializeMessageMedia, resolveAttachmentMimeType, toAnthropicImageBlock, uploadMediaFile, } from './media.js';
 export type { AnthropicImageBlock, AnthropicImageMimeType, MaterializeMediaOptions, MaterializedCanonAttachment, ReplyWithFileOptions, UploadMediaFileOptions, } from './media.js';
 export type { SessionConfig, Session } from './session-manager.js';
-export type { AgentContext, CanonContactRequest, CanonMessage, CanonConversation, CanonResolvedWorkSession, CanonWorkSession, CanonWorkSessionContext, CanonWorkSessionConversationRole, CanonWorkSessionDisclosureMode, CanonWorkSessionParticipant, CanonWorkSessionStatus, CreateWorkSessionOptions, SendLinkedMessageOptions, SendLinkedMessageResult, SendMessageOptions, CreateConversationOptions, UpdateWorkSessionConversationOptions, } from '@canonmsg/core';
+export type { AgentContext, CanonContactRequest, CanonMessage, CanonConversation, CanonSelfContext, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, CreateConversationOptions, } from '@canonmsg/core';
 export type { CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, ContactRequestHandler, MessageHandler, MessageHandlerContext, ProgressMessageOptions, ProgressMessageResult, ReachOutOptions, ReachOutResult, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';

package/dist/types.d.ts

@@ -1,5 +1,5 @@
-export type { AddMemberResult, AgentClientType, CanonRuntimeDescriptor, CanonMessage, CanonConversation, CanonContact, CanonContactRequest, CanonResolveAdmissionResult, ContactAddedPayload, ContactRemovedPayload, ContactSource, AgentContext, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonResolvedWorkSession, CanonWorkSession, CanonWorkSessionContext, CanonWorkSessionConversationRole, CanonWorkSessionDisclosureMode, CanonWorkSessionParticipant, CanonWorkSessionStatus, CreateWorkSessionOptions, SendLinkedMessageOptions, SendLinkedMessageResult, SendMessageOptions, CreateConversationOptions, TurnLifecycleState, UpdateWorkSessionConversationOptions, } from '@canonmsg/core';
-import type { AddMemberResult, CanonMessage, CanonConversation, CanonRuntimeActionDispatch, CreateWorkSessionOptions, SendMessageOptions, UpdateWorkSessionConversationOptions } from '@canonmsg/core';
+export type { AddMemberResult, AgentClientType, CanonRuntimeDescriptor, CanonMessage, CanonConversation, CanonContact, CanonContactRequest, CanonResolveAdmissionResult, ContactAddedPayload, ContactRemovedPayload, ContactSource, AgentContext, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonSelfContext, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, SessionConfig, CreateConversationOptions, TurnLifecycleState, } from '@canonmsg/core';
+import type { AddMemberResult, CanonMessage, CanonConversation, CanonRuntimeActionDispatch, SendMessageOptions, SendContextualSelfContextInput, SessionConfig } from '@canonmsg/core';
 import type { MaterializeMediaOptions, MaterializedCanonAttachment, ReplyWithFileOptions, UploadMediaFileOptions } from './media.js';
 export interface ProgressMessageOptions extends SendMessageOptions {
     /**
@@ -61,20 +61,16 @@ export interface MessageHandlerContext {
     addMember: (userId: string) => Promise<AddMemberResult>;
     /** Remove a member from this conversation (requires owner/admin role) */
     removeMember: (userId: string) => Promise<void>;
-    /** Create a Canon work session rooted in this conversation. */
-    createWorkSession: (options?: Omit<CreateWorkSessionOptions, 'conversationId'>) => Promise<import('@canonmsg/core').CanonResolvedWorkSession>;
-    /** Load this conversation's scoped view of a Canon work session. */
-    getWorkSession: (workSessionId: string, conversationId?: string) => Promise<import('@canonmsg/core').CanonResolvedWorkSession>;
-    /** Update or attach this conversation's scoped work-session context. */
-    updateWorkSessionContext: (workSessionId: string, options?: UpdateWorkSessionConversationOptions) => Promise<import('@canonmsg/core').CanonResolvedWorkSession>;
-    /** Send into another conversation under an existing or lazily created Canon work session. */
-    sendLinkedMessage: (targetConversationId: string, text: string, options?: Omit<import('@canonmsg/core').SendLinkedMessageOptions, 'sourceConversationId' | 'targetConversationId' | 'text'>) => Promise<import('@canonmsg/core').SendLinkedMessageResult>;
+    /** Send into another Canon conversation with private cross-session self-context. */
+    sendContextualMessage: (target: {
+        targetConversationId: string;
+    } | {
+        targetUserId: string;
+    }, text: string, options: Omit<import('@canonmsg/core').SendContextualMessageOptions, 'sourceConversationId' | 'targetConversationId' | 'targetUserId' | 'text'>) => Promise<import('@canonmsg/core').SendContextualMessageResult>;
     /** Trusted agent identity & access context */
     agent: import('@canonmsg/core').AgentContext;
-    /** Canon-provided shared task context for this turn, when attached to inbound messages. */
-    workSession?: import('@canonmsg/core').CanonWorkSessionContext | null;
-    /** All active Canon work sessions currently linked to this conversation. */
-    activeWorkSessions?: import('@canonmsg/core').CanonWorkSessionContext[];
+    /** Canon-provided private context explaining this agent's cross-session actions. */
+    selfContexts?: import('@canonmsg/core').CanonSelfContext[];
     /** Canon-managed local media access for the current conversation. */
     media: {
         materialize: (message?: CanonMessage, options?: Omit<MaterializeMediaOptions, 'agentId' | 'conversationId' | 'messageId'>) => Promise<MaterializedCanonAttachment[]>;
@@ -165,6 +161,9 @@ export type ReachOutResult = {
 } | {
     status: 'pending';
     requestId: string | null;
+} | {
+    status: 'setup_required';
+    reason: string;
 } | {
     status: 'blocked' | 'unavailable';
     reason: string;
@@ -174,4 +173,10 @@ export interface ReachOutOptions {
     text?: string;
     /** Optional contact-request note. Defaults to `text` when admission is `request-required`. */
     requestMessage?: string;
+    /** Explicit session setup to use when the contact-card target is an agent. */
+    sessionConfig?: SessionConfig | null;
+    /** Source conversation for contextual cross-session reach-outs. */
+    sourceConversationId?: string;
+    /** Private context for the agent when this reach-out sends a cross-session message. */
+    selfContext?: SendContextualSelfContextInput;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-sdk",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "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": "^0.15.3"
+    "@canonmsg/core": "^0.15.5"
   },
   "publishConfig": {
     "access": "public"