@canonmsg/agent-sdk 7.0.1 → 7.1.0

package/dist/canon-agent.d.ts

@@ -1,4 +1,4 @@
-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 AddMemberResult, type CanonContact, type CanonConversation, type CreateConversationResult, type CanonRuntimeActivityItem, type CanonRuntimeCommandDescriptor, type CanonRuntimeFact, type CanonRuntimePrimitiveId, type ContactCardPayload, type ClearRuntimeActivityOptions, type CreateContactRequestResult, type CanonVoiceSession, type CanonVoiceSessionToken, type CreateVoiceSessionOptions, type VoiceSessionEventPayload } from '@canonmsg/core';
 import type { CanonAgentConnectionOptions, CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, CreateConversationOptions, MessageHandler, MessageUpdatedHandler, ReachOutOptions, ReachOutResult, ContactRequestHandler, RuntimeSignalHandler, RuntimePrimitiveHandler } from './types.js';
 /**
  * Contact-graph operations exposed under `agent.contacts`. Wraps the REST
@@ -40,6 +40,10 @@ export declare class CanonAgent {
     private interruptHandler;
     private stopAndDropHandler;
     private newSessionHandler;
+    private callStartedHandler;
+    private callEndedHandler;
+    /** Whether the live SSE stream was opened with the voice family attached. */
+    private voiceEventsEnabled;
     private readonly primitiveHandlers;
     private primitiveFallbackHandler;
     /** Contact-graph operations (`agent.contacts.*`). Initialized in the constructor. */
@@ -96,6 +100,8 @@ export declare class CanonAgent {
     on(event: 'interrupt', handler: RuntimeSignalHandler): void;
     on(event: 'stopAndDrop', handler: RuntimeSignalHandler): void;
     on(event: 'newSession', handler: RuntimeSignalHandler): void;
+    on(event: 'callStarted', handler: (payload: VoiceSessionEventPayload) => void | Promise<void>): void;
+    on(event: 'callEnded', handler: (payload: VoiceSessionEventPayload) => void | Promise<void>): void;
     onPrimitive(primitive: CanonRuntimePrimitiveId | '*', handler: RuntimePrimitiveHandler): void;
     describeCommands(_provider?: string): ReadonlyArray<CanonRuntimeCommandDescriptor>;
     publishRuntimeFacts(conversationId: string, facts: ReadonlyArray<CanonRuntimeFact>): Promise<void>;
@@ -112,6 +118,16 @@ export declare class CanonAgent {
     private executeReachOut;
     start(): Promise<void>;
     createConversation(options: CreateConversationOptions): Promise<CreateConversationResult>;
+    /** Start (or rejoin) a call in a conversation and get the room token. */
+    startCall(options: CreateVoiceSessionOptions): Promise<CanonVoiceSessionToken>;
+    /** Join an active call session and get the room token. */
+    joinCall(conversationId: string, sessionId: string): Promise<CanonVoiceSessionToken>;
+    /** Decline an incoming call: stops this agent's ring only. */
+    declineCall(conversationId: string, sessionId: string): Promise<void>;
+    /** End an active call session for everyone. */
+    endCall(conversationId: string, sessionId: string): Promise<void>;
+    /** Fetch the current state of a call session. */
+    getCallState(conversationId: string, sessionId: string): Promise<CanonVoiceSession>;
     updateTopic(conversationId: string, topic: string): Promise<void>;
     leaveConversation(conversationId: string): Promise<void>;
     updateConversationName(conversationId: string, name: string): Promise<void>;

package/dist/canon-agent.js

@@ -257,6 +257,10 @@ export class CanonAgent {
     interruptHandler = null;
     stopAndDropHandler = null;
     newSessionHandler = null;
+    callStartedHandler = null;
+    callEndedHandler = null;
+    /** Whether the live SSE stream was opened with the voice family attached. */
+    voiceEventsEnabled = false;
     primitiveHandlers = new Map();
     primitiveFallbackHandler = null;
     /** Contact-graph operations (`agent.contacts.*`). Initialized in the constructor. */
@@ -426,6 +430,20 @@ export class CanonAgent {
         });
     }
     on(event, handler) {
+        if (event === 'callStarted' || event === 'callEnded') {
+            // The voice SSE family is negotiated at connect from handler presence,
+            // so call handlers registered after start() would never fire.
+            if (this.running && !this.voiceEventsEnabled) {
+                console.warn('[canon-sdk] on(%s) registered after connect: the voice event family was not requested at stream start, so call events will not arrive until the agent restarts. Register call handlers before start().', event);
+            }
+            if (event === 'callStarted') {
+                this.callStartedHandler = handler;
+            }
+            else {
+                this.callEndedHandler = handler;
+            }
+            return;
+        }
         if (event === 'message') {
             this.handler = handler;
             return;
@@ -656,7 +674,22 @@ export class CanonAgent {
         this.startRuntimeControlPolling();
         // 4. Start delivery
         const { RealtimeManager } = await import('./realtime.js');
-        const rtm = new RealtimeManager(this.options.apiKey, this.debouncer, agentId, this.options.streamUrl, this.apiClient);
+        this.voiceEventsEnabled = Boolean(this.callStartedHandler || this.callEndedHandler);
+        const rtm = new RealtimeManager(this.options.apiKey, this.debouncer, agentId, this.options.streamUrl, this.apiClient, { enableVoiceEvents: this.voiceEventsEnabled });
+        if (this.voiceEventsEnabled) {
+            rtm.setCallHandlers({
+                onCallStarted: (payload) => {
+                    void Promise.resolve(this.callStartedHandler?.(payload)).catch((error) => {
+                        console.error('[canon-sdk] callStarted handler failed:', error);
+                    });
+                },
+                onCallEnded: (payload) => {
+                    void Promise.resolve(this.callEndedHandler?.(payload)).catch((error) => {
+                        console.error('[canon-sdk] callEnded handler failed:', error);
+                    });
+                },
+            });
+        }
         rtm.setOnAgentContext((ctx) => {
             this.agentContext = ctx;
             this.ensureApprovalManager(ctx);
@@ -702,6 +735,31 @@ export class CanonAgent {
     async createConversation(options) {
         return this.apiClient.createConversation(options);
     }
+    // ── Calls ────────────────────────────────────────────────────────────
+    // These return the LiveKit room token payload; the agent brings its own
+    // RTC transport (e.g. @livekit/rtc-node as an optional, lazily imported
+    // dependency — the openclaw voice bridge is the reference implementation).
+    /** Start (or rejoin) a call in a conversation and get the room token. */
+    async startCall(options) {
+        return this.apiClient.createVoiceSession(options);
+    }
+    /** Join an active call session and get the room token. */
+    async joinCall(conversationId, sessionId) {
+        return this.apiClient.joinVoiceSession(conversationId, sessionId);
+    }
+    /** Decline an incoming call: stops this agent's ring only. */
+    async declineCall(conversationId, sessionId) {
+        return this.apiClient.declineVoiceSession(conversationId, sessionId);
+    }
+    /** End an active call session for everyone. */
+    async endCall(conversationId, sessionId) {
+        return this.apiClient.endVoiceSession(conversationId, sessionId);
+    }
+    /** Fetch the current state of a call session. */
+    async getCallState(conversationId, sessionId) {
+        const result = await this.apiClient.getVoiceSessionState(conversationId, sessionId);
+        return result.session;
+    }
     async updateTopic(conversationId, topic) {
         return this.apiClient.updateTopic(conversationId, topic);
     }

package/dist/realtime.d.ts

@@ -1,4 +1,4 @@
-import { type AgentContext, type CanonClient, type ContactAddedPayload, type ContactApprovedPayload, type ContactRemovedPayload, type ContactRequestPayload, type ConversationUpdatedPayload, type MessageUpdatedPayload } from '@canonmsg/core';
+import { type AgentContext, type CanonClient, type ContactAddedPayload, type ContactApprovedPayload, type ContactRemovedPayload, type ContactRequestPayload, type ConversationUpdatedPayload, type MessageUpdatedPayload, type VoiceSessionEventPayload } from '@canonmsg/core';
 import { Debouncer } from './debouncer.js';
 /**
  * Wraps @canonmsg/core's CanonStream with SDK-specific features:
@@ -26,7 +26,11 @@ export declare class RealtimeManager {
     private onMessageDeleted;
     private onConnected;
     private onDisconnected;
-    constructor(apiKey: string, debouncer: Debouncer, agentId: string, streamUrl?: string, apiClient?: CanonClient);
+    private onCallStarted;
+    private onCallEnded;
+    constructor(apiKey: string, debouncer: Debouncer, agentId: string, streamUrl?: string, apiClient?: CanonClient, options?: {
+        enableVoiceEvents?: boolean;
+    });
     private hasSeenInboundMessage;
     private recordSeenInboundMessage;
     private pruneRecentInboundMessageIds;
@@ -50,6 +54,10 @@ export declare class RealtimeManager {
         onConnected?: () => void;
         onDisconnected?: () => void;
     }): void;
+    setCallHandlers(handlers: {
+        onCallStarted?: (payload: VoiceSessionEventPayload) => void;
+        onCallEnded?: (payload: VoiceSessionEventPayload) => void;
+    }): void;
     start(): Promise<void>;
     stop(): void;
 }

package/dist/realtime.js

@@ -33,7 +33,9 @@ export class RealtimeManager {
     onMessageDeleted = null;
     onConnected = null;
     onDisconnected = null;
-    constructor(apiKey, debouncer, agentId, streamUrl, apiClient) {
+    onCallStarted = null;
+    onCallEnded = null;
+    constructor(apiKey, debouncer, agentId, streamUrl, apiClient, options) {
         this.debouncer = debouncer;
         this.agentId = agentId;
         this.stream = new CanonStream({
@@ -41,6 +43,21 @@ export class RealtimeManager {
             agentId,
             streamUrl,
             handler: {
+                // The voice family is requested from handler PRESENCE at stream
+                // construction, so these delegating closures exist only when the
+                // agent registered call handlers before connect — otherwise every
+                // SDK agent would cost the stream service a per-conversation
+                // voiceSessions listener for nothing.
+                ...(options?.enableVoiceEvents
+                    ? {
+                        onVoiceSessionStarted: (payload) => {
+                            this.onCallStarted?.(payload);
+                        },
+                        onVoiceSessionEnded: (payload) => {
+                            this.onCallEnded?.(payload);
+                        },
+                    }
+                    : {}),
                 onMessage: (payload) => {
                     // Cross-flush id dedupe: SSE replay overlap must never double-fire
                     // a turn for the same message.
@@ -183,6 +200,10 @@ export class RealtimeManager {
         this.onConnected = handlers.onConnected ?? null;
         this.onDisconnected = handlers.onDisconnected ?? null;
     }
+    setCallHandlers(handlers) {
+        this.onCallStarted = handlers.onCallStarted ?? null;
+        this.onCallEnded = handlers.onCallEnded ?? null;
+    }
     async start() {
         this.running = true;
         await this.stream.start();

package/package.json

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