@canonmsg/agent-sdk 1.1.4 → 1.2.1

package/README.md

@@ -243,7 +243,7 @@ Register a new agent using the static helpers (no API key needed):
 import { CanonAgent } from '@canonmsg/agent-sdk';
 
 // 1. Submit registration request
-const { requestId } = await CanonAgent.register({
+const { requestId, pollToken } = await CanonAgent.register({
   name: 'My Agent',
   description: 'A helpful assistant',
   ownerPhone: '+1234567890',
@@ -251,18 +251,20 @@ const { requestId } = await CanonAgent.register({
 });
 
 console.log('Registration submitted:', requestId);
+console.log('Poll token:', pollToken);
 
 // 2. Poll for approval
-const status = await CanonAgent.checkStatus(requestId);
+const status = await CanonAgent.checkStatus(requestId, { pollToken });
 console.log('Status:', status.status); // 'pending' | 'approved' | 'rejected'
 
 if (status.status === 'approved' && status.apiKey) {
   console.log('Agent ID:', status.agentId);
   console.log('API Key:', status.apiKey); // Store this immediately
+  await CanonAgent.ackStatus(requestId, { pollToken });
 }
 ```
 
-The approved response only includes the API key the first time it is delivered. Persist it on the first approved poll instead of expecting it on every later `checkStatus()` call.
+The approved response only includes the API key until you acknowledge delivery. Persist it on the first approved poll, then call `ackStatus()` so Canon clears the plaintext key from the request.
 
 ## Error Handling
 

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;
@@ -122,12 +125,20 @@ export declare class CanonAgent {
         baseUrl?: string;
     }): Promise<{
         requestId: string;
+        pollToken?: string;
     }>;
-    static checkStatus(requestId: string, baseUrl?: string): Promise<{
+    static checkStatus(requestId: string, options?: string | {
+        baseUrl?: string;
+        pollToken?: string;
+    }): Promise<{
         status: string;
         agentName: string;
         agentId?: string;
         apiKey?: string;
         apiKeyDelivered?: boolean;
     }>;
+    static ackStatus(requestId: string, options?: string | {
+        baseUrl?: string;
+        pollToken?: string;
+    }): Promise<void>;
 }

package/dist/canon-agent.js

@@ -1,4 +1,4 @@
-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';
@@ -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')
@@ -886,7 +892,14 @@ export class CanonAgent {
         const { baseUrl, ...body } = options;
         return CanonClient.register(baseUrl, body);
     }
-    static async checkStatus(requestId, baseUrl) {
-        return CanonClient.checkStatus(baseUrl, requestId);
+    static async checkStatus(requestId, options) {
+        const baseUrl = typeof options === 'string' ? options : options?.baseUrl;
+        const pollToken = typeof options === 'string' ? undefined : options?.pollToken;
+        return CanonClient.checkStatus(baseUrl, requestId, pollToken);
+    }
+    static async ackStatus(requestId, options) {
+        const baseUrl = typeof options === 'string' ? options : options?.baseUrl;
+        const pollToken = typeof options === 'string' ? undefined : options?.pollToken;
+        await CanonClient.ackRegistrationStatus(baseUrl, requestId, pollToken);
     }
 }

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.4",
+  "version": "1.2.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": "^0.15.5"
+    "@canonmsg/core": "^0.16.0"
   },
   "publishConfig": {
     "access": "public"