@canonmsg/agent-sdk 1.1.2 → 1.1.4

package/dist/canon-agent.js

@@ -1,8 +1,8 @@
-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';
-import { materializeMessageMedia, uploadMediaFile, } from './media.js';
+import { materializeMessageMedia, sendMediaFileMessage, uploadMediaFile, } from './media.js';
 import { SessionManager } from './session-manager.js';
 const AGENT_RUNTIME_HEARTBEAT_MS = 30_000;
 const SDK_RUNTIME_CAPABILITIES = {
@@ -152,7 +152,10 @@ export class CanonAgent {
         // Include the opener/request payloads in the dedupe key so two concurrent
         // 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 ?? ''}\u0000${JSON.stringify(options?.sessionConfig ?? null)}`;
+        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,6 +166,29 @@ 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,
@@ -634,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,
@@ -672,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,
@@ -693,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 {
@@ -726,22 +741,24 @@ export class CanonAgent {
                 }
                 catch { }
                 try {
-                    const uploaded = await uploadFile(filePath, options);
-                    const result = await this.apiClient.sendMessage(conversationId, text, {
+                    const result = await sendMediaFileMessage(this.apiClient, conversationId, filePath, text, {
                         ...(options?.replyTo ? { replyTo: options.replyTo } : {}),
                         ...(options?.replyToPosition != null
                             ? { 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],
+                        ...(options?.fileName ? { fileName: options.fileName } : {}),
+                        ...(options?.mimeType ? { mimeType: options.mimeType } : {}),
+                        ...(options?.durationMs != null ? { durationMs: options.durationMs } : {}),
                     });
                     await sleep(FINAL_MESSAGE_HANDOFF_MS);
                     return result;
@@ -767,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

@@ -3,8 +3,8 @@ export type { AgentContactsAPI, AgentUsersAPI } from './canon-agent.js';
 export { CanonApiError, HOST_ADMISSION_ACTION_CAPABILITIES, HOST_ADMISSION_ACTIONS_DISABLED, } from '@canonmsg/core';
 export type { CanonContact, CanonResolveAdmissionResult, ContactAddedPayload, ContactCardPayload, ContactRemovedPayload, ContactSource, HostAdmissionActionCapabilities, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, } from '@canonmsg/core';
 export { SessionManager } from './session-manager.js';
-export { getCodexImagePath, getMessageAttachments, inferUploadMimeType, isAnthropicImageAttachment, materializeAttachment, materializeMessageMedia, resolveAttachmentMimeType, toAnthropicImageBlock, uploadMediaFile, } from './media.js';
+export { DEFAULT_MEDIA_CACHE_DIR, getCodexImagePath, getMessageAttachments, inferUploadMimeType, isAnthropicImageAttachment, materializeAttachment, materializeMessageMedia, resolveAttachmentMimeType, sendMediaFileMessage, 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/index.js

@@ -1,4 +1,4 @@
 export { CanonAgent } from './canon-agent.js';
 export { CanonApiError, HOST_ADMISSION_ACTION_CAPABILITIES, HOST_ADMISSION_ACTIONS_DISABLED, } from '@canonmsg/core';
 export { SessionManager } from './session-manager.js';
-export { getCodexImagePath, getMessageAttachments, inferUploadMimeType, isAnthropicImageAttachment, materializeAttachment, materializeMessageMedia, resolveAttachmentMimeType, toAnthropicImageBlock, uploadMediaFile, } from './media.js';
+export { DEFAULT_MEDIA_CACHE_DIR, getCodexImagePath, getMessageAttachments, inferUploadMimeType, isAnthropicImageAttachment, materializeAttachment, materializeMessageMedia, resolveAttachmentMimeType, sendMediaFileMessage, toAnthropicImageBlock, uploadMediaFile, } from './media.js';

package/dist/media.d.ts

@@ -10,6 +10,7 @@ export interface MaterializeMediaOptions {
 export interface UploadMediaFileOptions {
     fileName?: string;
     mimeType?: string;
+    durationMs?: number;
 }
 export interface ReplyWithFileOptions extends Omit<SendMessageOptions, 'attachments' | 'contentType'>, UploadMediaFileOptions {
 }
@@ -39,6 +40,7 @@ export interface AnthropicImageBlock {
         data: string;
     };
 }
+export declare const DEFAULT_MEDIA_CACHE_DIR: string;
 export declare function getMessageAttachments(message: Pick<CanonMessage, 'attachments'>): MediaAttachment[];
 export declare function materializeAttachment(attachment: MediaAttachment, options: MaterializeMediaOptions & {
     index?: number;
@@ -49,6 +51,9 @@ export declare function uploadMediaFile(client: CanonClient, conversationId: str
     url: string;
     attachment: MediaAttachment;
 }>;
+export declare function sendMediaFileMessage(client: CanonClient, conversationId: string, filePath: string, text?: string, options?: ReplyWithFileOptions): Promise<{
+    messageId: string;
+}>;
 /**
  * Resolve the effective MIME type of a materialized attachment, falling back
  * to filename/URL extensions when the server didn't tell us explicitly.

package/dist/media.js

@@ -7,7 +7,7 @@ const ANTHROPIC_IMAGE_MIME_TYPES = new Set([
     'image/gif',
     'image/webp',
 ]);
-const DEFAULT_MEDIA_CACHE_DIR = join(CANON_DIR, 'media-cache');
+export const DEFAULT_MEDIA_CACHE_DIR = join(CANON_DIR, 'media-cache');
 const EXTENSION_BY_MIME = {
     'application/json': 'json',
     'application/pdf': 'pdf',
@@ -117,7 +117,7 @@ export async function materializeAttachment(attachment, options) {
         }
         responseMimeType = response.headers.get('content-type');
         const body = Buffer.from(await response.arrayBuffer());
-        await writeFile(path, body);
+        await writeFile(path, body, { mode: 0o644 });
     }
     return {
         ...attachment,
@@ -150,7 +150,33 @@ export async function uploadMediaFile(client, conversationId, filePath, options)
     const buffer = await readFile(filePath);
     const mimeType = inferUploadMimeType(filePath, options?.mimeType);
     const fileName = options?.fileName ?? basename(filePath);
-    return client.uploadMedia(conversationId, buffer.toString('base64'), mimeType, fileName);
+    const uploaded = await client.uploadMedia(conversationId, buffer.toString('base64'), mimeType, fileName);
+    if (uploaded.attachment.kind === 'audio'
+        && typeof options?.durationMs === 'number'
+        && Number.isFinite(options.durationMs)
+        && options.durationMs > 0) {
+        return {
+            ...uploaded,
+            attachment: {
+                ...uploaded.attachment,
+                durationMs: Math.round(options.durationMs),
+            },
+        };
+    }
+    return uploaded;
+}
+export async function sendMediaFileMessage(client, conversationId, filePath, text = '', options) {
+    const { fileName, mimeType, durationMs, ...sendOptions } = options ?? {};
+    const uploaded = await uploadMediaFile(client, conversationId, filePath, {
+        ...(fileName ? { fileName } : {}),
+        ...(mimeType ? { mimeType } : {}),
+        ...(durationMs != null ? { durationMs } : {}),
+    });
+    return client.sendMessage(conversationId, text, {
+        ...sendOptions,
+        contentType: uploaded.attachment.kind,
+        attachments: [uploaded.attachment],
+    });
 }
 /**
  * Resolve the effective MIME type of a materialized attachment, falling back

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, SessionConfig, CreateConversationOptions, TurnLifecycleState, UpdateWorkSessionConversationOptions, } from '@canonmsg/core';
-import type { AddMemberResult, CanonMessage, CanonConversation, CanonRuntimeActionDispatch, CreateWorkSessionOptions, SendMessageOptions, SessionConfig, 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[]>;
@@ -179,4 +175,8 @@ export interface ReachOutOptions {
     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.2",
+  "version": "1.1.4",
   "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.4"
+    "@canonmsg/core": "^0.15.5"
   },
   "publishConfig": {
     "access": "public"