@canonmsg/agent-sdk 1.1.3 → 1.2.0

package/dist/canon-agent.d.ts

@@ -32,6 +32,7 @@ export declare class CanonAgent {
     private contactRemovedHandler;
     private interruptHandler;
     private stopAndDropHandler;
+    private newSessionHandler;
     /** Contact-graph operations (`agent.contacts.*`). Initialized in the constructor. */
     readonly contacts: AgentContactsAPI;
     /** Block/unblock operations (`agent.users.*`). Initialized in the constructor. */
@@ -53,6 +54,7 @@ export declare class CanonAgent {
     on(event: 'contactRemoved', handler: ContactRemovedHandler): void;
     on(event: 'interrupt', handler: RuntimeSignalHandler): void;
     on(event: 'stopAndDrop', handler: RuntimeSignalHandler): void;
+    on(event: 'newSession', handler: RuntimeSignalHandler): void;
     /**
      * Resolve admission live for a target user (typically read off a shared
      * contact card) and route into either an immediate message or a contact
@@ -94,6 +96,7 @@ export declare class CanonAgent {
     stop(): Promise<void>;
     private hasInterruptSupport;
     private hasStopAndDropSupport;
+    private hasNewSessionSupport;
     private hasRuntimeSignalSupport;
     private buildRuntimeDescriptor;
     private buildRuntimeCapabilities;

package/dist/canon-agent.js

@@ -1,8 +1,8 @@
-import { CanonClient, createRuntimeStatePublisher, FINAL_MESSAGE_HANDOFF_MS, initRTDBAuth, rtdbRead, rtdbWrite, normalizeTurnMetadata, reachOutToCanonContact, } from '@canonmsg/core';
+import { CanonClient, createRuntimeStatePublisher, FINAL_MESSAGE_HANDOFF_MS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, 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 = {
@@ -18,26 +18,6 @@ const DEFAULT_SDK_RUNTIME_DESCRIPTOR = {
     supportsInterrupt: false,
     streamingTextMode: 'snapshot',
 };
-const SDK_STOP_ACTION = {
-    id: 'stop',
-    label: 'Stop',
-    description: 'Interrupt the current SDK agent turn.',
-    aliases: ['stop'],
-    category: 'turn',
-    placements: ['composer_slash', 'command_palette'],
-    availability: ['busy'],
-    dispatch: { kind: 'signal', signal: 'interrupt' },
-};
-const SDK_STOP_AND_DROP_ACTION = {
-    id: 'stop-and-clear-queue',
-    label: 'Stop & clear queue',
-    description: 'Interrupt the current SDK agent turn and drop queued Canon messages.',
-    aliases: ['stop-clear', 'clear-queue'],
-    category: 'turn',
-    placements: ['composer_slash', 'command_palette', 'session_strip'],
-    availability: ['busy_with_queue'],
-    dispatch: { kind: 'signal', signal: 'stop_and_drop' },
-};
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -55,6 +35,7 @@ export class CanonAgent {
     contactRemovedHandler = null;
     interruptHandler = null;
     stopAndDropHandler = null;
+    newSessionHandler = null;
     /** Contact-graph operations (`agent.contacts.*`). Initialized in the constructor. */
     contacts;
     /** Block/unblock operations (`agent.users.*`). Initialized in the constructor. */
@@ -100,6 +81,7 @@ export class CanonAgent {
         }
         this.interruptHandler = options.runtimeControls?.onInterrupt ?? null;
         this.stopAndDropHandler = options.runtimeControls?.onStopAndDrop ?? null;
+        this.newSessionHandler = options.runtimeControls?.onNewSession ?? null;
     }
     on(event, handler) {
         if (event === 'message') {
@@ -138,6 +120,16 @@ export class CanonAgent {
             void this.publishAgentRuntime().catch(() => { });
             return;
         }
+        if (event === 'newSession') {
+            this.newSessionHandler = handler;
+            if (this.running) {
+                void this.baselineRuntimeControlSignals(this.cachedConversationIds)
+                    .then(() => this.startRuntimeControlPolling())
+                    .catch(() => { });
+            }
+            void this.publishAgentRuntime().catch(() => { });
+            return;
+        }
         this.contactRemovedHandler = handler;
     }
     /**
@@ -366,13 +358,17 @@ export class CanonAgent {
     hasStopAndDropSupport() {
         return Boolean(this.stopAndDropHandler);
     }
+    hasNewSessionSupport() {
+        return Boolean(this.newSessionHandler);
+    }
     hasRuntimeSignalSupport() {
-        return this.hasInterruptSupport() || this.hasStopAndDropSupport();
+        return this.hasInterruptSupport() || this.hasStopAndDropSupport() || this.hasNewSessionSupport();
     }
     buildRuntimeDescriptor() {
         const source = this.options.runtimeDescriptor ?? DEFAULT_SDK_RUNTIME_DESCRIPTOR;
         const hasInterrupt = this.hasInterruptSupport();
         const hasStopAndDrop = this.hasStopAndDropSupport();
+        const hasNewSession = this.hasNewSessionSupport();
         const actions = [...(source.actions ?? [])].filter((action) => {
             if (action.dispatch.kind !== 'signal')
                 return true;
@@ -380,15 +376,21 @@ export class CanonAgent {
                 return hasInterrupt;
             if (action.dispatch.signal === 'stop_and_drop')
                 return hasStopAndDrop;
+            if (action.dispatch.signal === 'new_session')
+                return hasNewSession;
             return false;
         });
         const hasInterruptAction = actions.some((action) => action.dispatch.kind === 'signal' && action.dispatch.signal === 'interrupt');
         const hasStopAndDropAction = actions.some((action) => action.dispatch.kind === 'signal' && action.dispatch.signal === 'stop_and_drop');
+        const hasNewSessionAction = actions.some((action) => action.dispatch.kind === 'signal' && action.dispatch.signal === 'new_session');
         if (hasInterrupt && !hasInterruptAction) {
-            actions.push(SDK_STOP_ACTION);
+            actions.push(RUNTIME_STOP_ACTION);
         }
         if (hasStopAndDrop && this.sessionManager && !hasStopAndDropAction) {
-            actions.push(SDK_STOP_AND_DROP_ACTION);
+            actions.push(RUNTIME_STOP_AND_DROP_ACTION);
+        }
+        if (hasNewSession && !hasNewSessionAction) {
+            actions.push(RUNTIME_NEW_SESSION_ACTION);
         }
         return {
             ...source,
@@ -476,23 +478,27 @@ export class CanonAgent {
         if (!this.agentId)
             return;
         const signal = raw.type;
-        if (signal !== 'interrupt' && signal !== 'stop_and_drop')
+        if (signal !== 'interrupt' && signal !== 'stop_and_drop' && signal !== 'new_session')
             return;
         const timestamp = Number(raw.updatedAt ?? 0);
         if (timestamp <= (this.lastSeenSignal.get(conversationId) ?? 0))
             return;
         this.lastSeenSignal.set(conversationId, timestamp);
-        const handler = signal === 'stop_and_drop'
-            ? this.stopAndDropHandler
-            : this.interruptHandler;
+        const handler = signal === 'new_session'
+            ? this.newSessionHandler
+            : signal === 'stop_and_drop'
+                ? this.stopAndDropHandler
+                : this.interruptHandler;
         if (!handler) {
             await Promise.resolve(rtdbWrite(`/control/${conversationId}/${this.agentId}/signal`, null)).catch(() => { });
             return;
         }
         const abortSignal = this.abortActiveTurns(conversationId);
-        const droppedMessages = signal === 'stop_and_drop'
-            ? this.sessionManager?.dropQueued(conversationId) ?? []
-            : [];
+        const droppedMessages = signal === 'new_session'
+            ? this.sessionManager?.resetSession(conversationId) ?? []
+            : signal === 'stop_and_drop'
+                ? this.sessionManager?.dropQueued(conversationId) ?? []
+                : [];
         const droppedMessageIds = droppedMessages.map((message) => message.id);
         await Promise.all(droppedMessages.map((message) => {
             if (message.metadata?.inboundDisposition !== 'queued')
@@ -741,8 +747,7 @@ 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 }
@@ -757,8 +762,9 @@ export class CanonAgent {
                             turnSemantics: 'turn_complete',
                             turnComplete: true,
                         },
-                        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;

package/dist/index.d.ts

@@ -3,7 +3,7 @@ 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, CanonSelfContext, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, CreateConversationOptions, } from '@canonmsg/core';

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/session-manager.d.ts

@@ -65,6 +65,8 @@ export declare class SessionManager {
     getQueueDepth(conversationId: string): number;
     /** Drop queued, not-yet-running batches for a conversation. */
     dropQueued(conversationId: string): CanonMessage[];
+    /** Drop queued work and clear retained context for a conversation. */
+    resetSession(conversationId: string): CanonMessage[];
     /** Clean up all state */
     destroy(): void;
 }

package/dist/session-manager.js

@@ -213,6 +213,14 @@ export class SessionManager {
         }
         return droppedMessages;
     }
+    /** Drop queued work and clear retained context for a conversation. */
+    resetSession(conversationId) {
+        const droppedMessages = this.dropQueued(conversationId);
+        this.sessions.delete(conversationId);
+        this.seenMessages.delete(conversationId);
+        this.seededSessions.delete(conversationId);
+        return droppedMessages;
+    }
     /** Clean up all state */
     destroy() {
         if (this.sweepTimer) {

package/dist/types.d.ts

@@ -115,6 +115,7 @@ export type RuntimeSignalHandler = (context: RuntimeSignalContext) => void | Pro
 export interface RuntimeControlHandlers {
     onInterrupt?: RuntimeSignalHandler;
     onStopAndDrop?: RuntimeSignalHandler;
+    onNewSession?: RuntimeSignalHandler;
 }
 export interface CanonAgentOptions {
     apiKey: string;

package/package.json

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