@canonmsg/agent-sdk 1.0.0 → 1.1.1

package/README.md

@@ -41,6 +41,7 @@ No additional dependencies required — the SDK uses native `fetch` and `Readabl
 | `sessions` | `SessionOptions` | `undefined` | Enable per-conversation session queues and persistent metadata |
 | `clientType` | `AgentClientType` | `'generic'` | Agent runtime label used for Canon capability detection |
 | `runtimeDescriptor` | `CanonRuntimeDescriptor` | minimal generic descriptor | Optional setup/live controls and runtime capability metadata for Canon UI |
+| `runtimeControls` | `RuntimeControlHandlers` | `undefined` | Optional interrupt / stop-clear handlers for Canon working-state controls |
 | `sessionState` | `boolean` | `false` | Publish RTDB session-state for the conversations this agent is active in |
 
 ### Optional runtime controls
@@ -88,6 +89,29 @@ const agent = new CanonAgent({
 });
 ```
 
+SDK agents only advertise Stop or Send Now when they register runtime-control handlers. Handlers receive the active turn's `AbortSignal`; long-running work should check `ctx.abortSignal.aborted` or pass the signal into cancellable APIs.
+
+```typescript
+const agent = new CanonAgent({
+  apiKey: process.env.CANON_API_KEY!,
+  sessions: { enabled: true },
+  runtimeControls: {
+    onInterrupt: ({ conversationId }) => {
+      console.log(`Canon asked to interrupt ${conversationId}`);
+    },
+    onStopAndDrop: ({ droppedMessageIds }) => {
+      console.log('Dropped queued messages:', droppedMessageIds);
+    },
+  },
+});
+
+agent.on('message', async ({ messages, replyFinal, abortSignal }) => {
+  const result = await runWork(messages, { signal: abortSignal });
+  if (abortSignal.aborted) return;
+  await replyFinal(result);
+});
+```
+
 The descriptor only drives Canon UI and validation. Your SDK agent is still responsible for reading session config and safely mapping selected values to local directories.
 
 Node SDK builders can reuse `buildConfiguredWorkspaceOptionsWithRoots` from `@canonmsg/core` to produce the same stable project IDs and root metadata used by the first-party Claude Code and Codex hosts.

package/dist/canon-agent.d.ts

@@ -1,5 +1,5 @@
 import { type AddMemberResult, type CanonContact, type ContactCardPayload, type CreateContactRequestResult } from '@canonmsg/core';
-import type { CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, CreateConversationOptions, MessageHandler, ReachOutOptions, ReachOutResult, ContactRequestHandler } from './types.js';
+import type { CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, CreateConversationOptions, MessageHandler, ReachOutOptions, ReachOutResult, ContactRequestHandler, RuntimeSignalHandler } from './types.js';
 /**
  * Contact-graph operations exposed under `agent.contacts`. Wraps the REST
  * endpoints in CanonClient — the same surface a human user would hit through
@@ -30,6 +30,8 @@ export declare class CanonAgent {
     private contactApprovedHandler;
     private contactAddedHandler;
     private contactRemovedHandler;
+    private interruptHandler;
+    private stopAndDropHandler;
     /** Contact-graph operations (`agent.contacts.*`). Initialized in the constructor. */
     readonly contacts: AgentContactsAPI;
     /** Block/unblock operations (`agent.users.*`). Initialized in the constructor. */
@@ -40,12 +42,17 @@ export declare class CanonAgent {
     private cachedConversationIds;
     private running;
     private runtimeHeartbeatTimer;
+    private runtimeControlPollTimer;
+    private readonly lastSeenSignal;
+    private readonly activeAbortControllers;
     constructor(options: CanonAgentOptions);
     on(event: 'message', handler: MessageHandler): void;
     on(event: 'contactRequest', handler: ContactRequestHandler): void;
     on(event: 'contactApproved', handler: ContactRequestHandler): void;
     on(event: 'contactAdded', handler: ContactAddedHandler): void;
     on(event: 'contactRemoved', handler: ContactRemovedHandler): void;
+    on(event: 'interrupt', handler: RuntimeSignalHandler): void;
+    on(event: 'stopAndDrop', 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
@@ -55,7 +62,6 @@ export declare class CanonAgent {
      */
     reachOut(card: ContactCardPayload, options?: ReachOutOptions): Promise<ReachOutResult>;
     private executeReachOut;
-    private openConversationAndMaybeMessage;
     start(): Promise<void>;
     createConversation(options: CreateConversationOptions): Promise<{
         conversationId: string;
@@ -86,10 +92,24 @@ export declare class CanonAgent {
     private handleContactRequestEvent;
     private handleContactGraphEvent;
     stop(): Promise<void>;
+    private hasInterruptSupport;
+    private hasStopAndDropSupport;
+    private hasRuntimeSignalSupport;
+    private buildRuntimeDescriptor;
+    private buildRuntimeCapabilities;
     private publishAgentRuntime;
     private startRuntimeHeartbeat;
     private stopRuntimeHeartbeat;
     private clearAgentRuntime;
+    private rememberConversationId;
+    private baselineRuntimeControlSignals;
+    private startRuntimeControlPolling;
+    private stopRuntimeControlPolling;
+    private pollRuntimeControlSignals;
+    private handleRuntimeSignal;
+    private abortActiveTurns;
+    private resolveBatchDeliveryIntent;
+    private notifyMessageInterrupt;
     private createRuntimeStatePublisher;
     private handleMessages;
     private executeHandler;

package/dist/canon-agent.js

@@ -1,4 +1,4 @@
-import { CanonClient, createRuntimeStatePublisher, FINAL_MESSAGE_HANDOFF_MS, initRTDBAuth, mergeWorkSessionContexts, } from '@canonmsg/core';
+import { CanonClient, createRuntimeStatePublisher, FINAL_MESSAGE_HANDOFF_MS, initRTDBAuth, rtdbRead, rtdbWrite, mergeWorkSessionContexts, normalizeTurnMetadata, reachOutToCanonContact, } from '@canonmsg/core';
 import { randomUUID } from 'node:crypto';
 import { AuthManager } from './auth.js';
 import { Debouncer } from './debouncer.js';
@@ -18,6 +18,26 @@ 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));
 }
@@ -33,6 +53,8 @@ export class CanonAgent {
     contactApprovedHandler = null;
     contactAddedHandler = null;
     contactRemovedHandler = null;
+    interruptHandler = null;
+    stopAndDropHandler = null;
     /** Contact-graph operations (`agent.contacts.*`). Initialized in the constructor. */
     contacts;
     /** Block/unblock operations (`agent.users.*`). Initialized in the constructor. */
@@ -43,6 +65,9 @@ export class CanonAgent {
     cachedConversationIds = [];
     running = false;
     runtimeHeartbeatTimer = null;
+    runtimeControlPollTimer = null;
+    lastSeenSignal = new Map();
+    activeAbortControllers = new Map();
     constructor(options) {
         this.options = {
             baseUrl: 'https://api-6m6mlelskq-uc.a.run.app',
@@ -73,6 +98,8 @@ export class CanonAgent {
                 idleTimeoutMs: options.sessions.idleTimeoutMs,
             });
         }
+        this.interruptHandler = options.runtimeControls?.onInterrupt ?? null;
+        this.stopAndDropHandler = options.runtimeControls?.onStopAndDrop ?? null;
     }
     on(event, handler) {
         if (event === 'message') {
@@ -91,6 +118,26 @@ export class CanonAgent {
             this.contactAddedHandler = handler;
             return;
         }
+        if (event === 'interrupt') {
+            this.interruptHandler = handler;
+            if (this.running) {
+                void this.baselineRuntimeControlSignals(this.cachedConversationIds)
+                    .then(() => this.startRuntimeControlPolling())
+                    .catch(() => { });
+            }
+            void this.publishAgentRuntime().catch(() => { });
+            return;
+        }
+        if (event === 'stopAndDrop') {
+            this.stopAndDropHandler = handler;
+            if (this.running) {
+                void this.baselineRuntimeControlSignals(this.cachedConversationIds)
+                    .then(() => this.startRuntimeControlPolling())
+                    .catch(() => { });
+            }
+            void this.publishAgentRuntime().catch(() => { });
+            return;
+        }
         this.contactRemovedHandler = handler;
     }
     /**
@@ -116,45 +163,11 @@ export class CanonAgent {
         return promise;
     }
     async executeReachOut(targetUserId, options) {
-        const { admission } = await this.apiClient.resolveAdmission(targetUserId);
-        if (admission.state === 'allowed' && admission.canMessage) {
-            return this.openConversationAndMaybeMessage(targetUserId, options);
-        }
-        if (admission.state === 'pending-outbound') {
-            return { status: 'pending', requestId: admission.pendingRequestId ?? null };
-        }
-        if (admission.state === 'request-required' && admission.canRequestContact) {
-            const result = await this.apiClient.createContactRequest(targetUserId, options?.requestMessage ?? null);
-            // The server may report 'open' if the target's policy flipped between
-            // the resolveAdmission call and the request. No request doc was
-            // written — fall through to the messaging path so the caller's intent
-            // ("reach this user") is honored end-to-end. Without this, the caller
-            // would get { status: 'requested' } despite no request existing.
-            if (result.status === 'open') {
-                return this.openConversationAndMaybeMessage(targetUserId, options);
-            }
-            // 'duplicate' means a pending request already existed; surface as
-            // 'pending'. 'created' is the normal "request just landed" path.
-            if (result.status === 'duplicate') {
-                return { status: 'pending', requestId: result.requestId };
-            }
-            return { status: 'requested', requestId: result.requestId };
-        }
-        if (admission.state === 'blocked') {
-            return { status: 'blocked', reason: 'blocked' };
-        }
-        return { status: 'unavailable', reason: admission.state };
-    }
-    async openConversationAndMaybeMessage(targetUserId, options) {
-        const { conversationId } = await this.apiClient.createConversation({
-            type: 'direct',
+        return reachOutToCanonContact(this.apiClient, {
             targetUserId,
+            text: options?.text ?? null,
+            requestMessage: options?.requestMessage ?? null,
         });
-        if (options?.text) {
-            const { messageId } = await this.apiClient.sendMessage(conversationId, options.text);
-            return { status: 'messaged', conversationId, messageId };
-        }
-        return { status: 'messaged', conversationId };
     }
     async start() {
         if (this.running)
@@ -167,6 +180,7 @@ export class CanonAgent {
         console.log(`[canon-sdk] Authenticated as ${agentId}`);
         // 2. Wire debouncer to handler
         this.debouncer.setCallback(async (conversationId, messages) => {
+            this.rememberConversationId(conversationId);
             await this.handleMessages(conversationId, messages);
         });
         // 3. Fetch conversations (used for delivery mode + session state)
@@ -208,6 +222,8 @@ export class CanonAgent {
                 console.log(`[canon-sdk] Session state reported for ${this.cachedConversationIds.length} conversations`);
             }
         }
+        await this.baselineRuntimeControlSignals(this.cachedConversationIds);
+        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);
@@ -297,6 +313,7 @@ export class CanonAgent {
         if (!this.running)
             return;
         this.running = false;
+        this.stopRuntimeControlPolling();
         // Clear session state if enabled (uses cached IDs — no network call during shutdown)
         const runtimeState = this.createRuntimeStatePublisher();
         if (this.options.sessionState && runtimeState) {
@@ -316,12 +333,55 @@ export class CanonAgent {
         this.debouncer.destroy();
         console.log('[canon-sdk] Stopped');
     }
+    hasInterruptSupport() {
+        return Boolean(this.interruptHandler);
+    }
+    hasStopAndDropSupport() {
+        return Boolean(this.stopAndDropHandler);
+    }
+    hasRuntimeSignalSupport() {
+        return this.hasInterruptSupport() || this.hasStopAndDropSupport();
+    }
+    buildRuntimeDescriptor() {
+        const source = this.options.runtimeDescriptor ?? DEFAULT_SDK_RUNTIME_DESCRIPTOR;
+        const hasInterrupt = this.hasInterruptSupport();
+        const hasStopAndDrop = this.hasStopAndDropSupport();
+        const actions = [...(source.actions ?? [])].filter((action) => {
+            if (action.dispatch.kind !== 'signal')
+                return true;
+            if (action.dispatch.signal === 'interrupt')
+                return hasInterrupt;
+            if (action.dispatch.signal === 'stop_and_drop')
+                return hasStopAndDrop;
+            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');
+        if (hasInterrupt && !hasInterruptAction) {
+            actions.push(SDK_STOP_ACTION);
+        }
+        if (hasStopAndDrop && this.sessionManager && !hasStopAndDropAction) {
+            actions.push(SDK_STOP_AND_DROP_ACTION);
+        }
+        return {
+            ...source,
+            supportsInterrupt: hasInterrupt,
+            actions,
+        };
+    }
+    buildRuntimeCapabilities() {
+        return {
+            ...SDK_RUNTIME_CAPABILITIES,
+            supportsInterrupt: this.hasInterruptSupport(),
+            supportsQueue: Boolean(this.sessionManager),
+        };
+    }
     async publishAgentRuntime() {
         const publisher = this.createRuntimeStatePublisher();
         if (!publisher)
             return;
         await publisher.publishAgentRuntime({
-            runtimeDescriptor: this.options.runtimeDescriptor ?? DEFAULT_SDK_RUNTIME_DESCRIPTOR,
+            runtimeDescriptor: this.buildRuntimeDescriptor(),
         });
     }
     startRuntimeHeartbeat() {
@@ -343,6 +403,113 @@ export class CanonAgent {
     async clearAgentRuntime() {
         await Promise.resolve(this.createRuntimeStatePublisher()?.clearAgentRuntime()).catch(() => { });
     }
+    rememberConversationId(conversationId) {
+        if (this.cachedConversationIds.includes(conversationId))
+            return;
+        this.cachedConversationIds.push(conversationId);
+    }
+    async baselineRuntimeControlSignals(conversationIds) {
+        if (!this.agentId || !this.hasRuntimeSignalSupport())
+            return;
+        await Promise.all(conversationIds.map(async (conversationId) => {
+            const raw = await Promise.resolve(rtdbRead(`/control/${conversationId}/${this.agentId}/signal`)).catch(() => null);
+            if (!raw || typeof raw !== 'object')
+                return;
+            const timestamp = Number(raw.updatedAt ?? 0);
+            if (timestamp > 0) {
+                this.lastSeenSignal.set(conversationId, timestamp);
+            }
+        }));
+    }
+    startRuntimeControlPolling() {
+        if (!this.agentId || this.runtimeControlPollTimer || !this.hasRuntimeSignalSupport())
+            return;
+        this.runtimeControlPollTimer = setInterval(() => {
+            void this.pollRuntimeControlSignals();
+        }, 2_000);
+        this.runtimeControlPollTimer.unref?.();
+    }
+    stopRuntimeControlPolling() {
+        if (!this.runtimeControlPollTimer)
+            return;
+        clearInterval(this.runtimeControlPollTimer);
+        this.runtimeControlPollTimer = null;
+    }
+    async pollRuntimeControlSignals() {
+        if (!this.agentId || !this.hasRuntimeSignalSupport())
+            return;
+        await Promise.all(this.cachedConversationIds.map(async (conversationId) => {
+            const raw = await Promise.resolve(rtdbRead(`/control/${conversationId}/${this.agentId}/signal`)).catch(() => null);
+            if (!raw || typeof raw !== 'object')
+                return;
+            await this.handleRuntimeSignal(conversationId, raw);
+        }));
+    }
+    async handleRuntimeSignal(conversationId, raw) {
+        if (!this.agentId)
+            return;
+        const signal = raw.type;
+        if (signal !== 'interrupt' && signal !== 'stop_and_drop')
+            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;
+        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 droppedMessageIds = droppedMessages.map((message) => message.id);
+        await Promise.all(droppedMessages.map((message) => {
+            if (message.metadata?.inboundDisposition !== 'queued')
+                return Promise.resolve();
+            return this.apiClient.updateMessageDisposition(conversationId, message.id, 'rejected').catch(() => { });
+        }));
+        await Promise.resolve(handler?.({
+            conversationId,
+            signal: signal,
+            updatedAt: timestamp || undefined,
+            abortSignal,
+            droppedMessageIds,
+        })).catch((error) => {
+            console.error(`[canon-sdk] Runtime ${signal} handler failed for ${conversationId}:`, error);
+        });
+        await Promise.resolve(rtdbWrite(`/control/${conversationId}/${this.agentId}/signal`, null)).catch(() => { });
+    }
+    abortActiveTurns(conversationId) {
+        const controllers = this.activeAbortControllers.get(conversationId);
+        if (!controllers || controllers.size === 0)
+            return undefined;
+        const abortSignal = controllers.values().next().value?.signal;
+        for (const controller of controllers) {
+            controller.abort();
+        }
+        return abortSignal;
+    }
+    resolveBatchDeliveryIntent(messages) {
+        return messages.some((message) => normalizeTurnMetadata(message.metadata)?.deliveryIntent === 'interrupt')
+            ? 'interrupt'
+            : 'queue';
+    }
+    async notifyMessageInterrupt(conversationId, abortSignal) {
+        if (!abortSignal || !this.interruptHandler)
+            return;
+        await Promise.resolve(this.interruptHandler({
+            conversationId,
+            signal: 'interrupt',
+            abortSignal,
+            droppedMessageIds: [],
+        })).catch((error) => {
+            console.error(`[canon-sdk] Runtime interrupt handler failed for ${conversationId}:`, error);
+        });
+    }
     createRuntimeStatePublisher() {
         if (!this.agentId)
             return null;
@@ -357,10 +524,14 @@ export class CanonAgent {
             console.warn(`[canon-sdk] No message handler registered — messages for ${conversationId} dropped. Call agent.on('message', handler) before starting.`);
             return;
         }
+        const deliveryIntent = this.resolveBatchDeliveryIntent(messages);
+        const shouldInterrupt = deliveryIntent === 'interrupt' && this.hasInterruptSupport();
+        const abortSignal = shouldInterrupt ? this.abortActiveTurns(conversationId) : undefined;
+        await this.notifyMessageInterrupt(conversationId, abortSignal);
         if (this.sessionManager) {
             await this.sessionManager.enqueue(conversationId, messages, async (session, newMessages) => {
                 await this.executeHandler(conversationId, newMessages, session);
-            });
+            }, { toFront: shouldInterrupt });
         }
         else {
             await this.executeHandler(conversationId, messages);
@@ -376,6 +547,10 @@ export class CanonAgent {
         const agentId = this.agentId;
         const runtimeState = this.createRuntimeStatePublisher();
         const queueDepth = () => this.sessionManager?.getQueueDepth(conversationId) ?? 0;
+        const abortController = new AbortController();
+        const activeControllers = this.activeAbortControllers.get(conversationId) ?? new Set();
+        activeControllers.add(abortController);
+        this.activeAbortControllers.set(conversationId, activeControllers);
         const writeTurn = async (state) => {
             if (!runtimeState || !agentId)
                 return;
@@ -385,7 +560,7 @@ export class CanonAgent {
                 state,
                 queueDepth: queueDepth(),
                 currentSpeakerId: agentId,
-                capabilities: SDK_RUNTIME_CAPABILITIES,
+                capabilities: this.buildRuntimeCapabilities(),
                 openedAt: turnOpenedAt,
                 ...(state === 'completed' || state === 'interrupted' || state === 'idle'
                     ? { completedAt: { '.sv': 'timestamp' } }
@@ -598,6 +773,7 @@ export class CanonAgent {
                 agent,
                 workSession,
                 activeWorkSessions,
+                abortSignal: abortController.signal,
                 media: {
                     materialize: (message = hydratedMessages[hydratedMessages.length - 1], options) => {
                         if (!message)
@@ -671,6 +847,11 @@ export class CanonAgent {
             await writeTurn('interrupted');
         }
         finally {
+            const activeControllers = this.activeAbortControllers.get(conversationId);
+            activeControllers?.delete(abortController);
+            if (activeControllers?.size === 0) {
+                this.activeAbortControllers.delete(conversationId);
+            }
             clearInterval(thinkingKeepalive);
             // Always clear typing when done
             try {

package/dist/session-manager.d.ts

@@ -18,6 +18,10 @@ export interface Session {
     lastActiveAt: number;
 }
 type SessionHandler = (session: Session, newMessages: CanonMessage[]) => Promise<void>;
+export interface EnqueueOptions {
+    /** Place this batch ahead of other not-yet-running batches. */
+    toFront?: boolean;
+}
 /**
  * Manages per-conversation sessions with:
  * - In-memory message buffer per session
@@ -40,6 +44,8 @@ export declare class SessionManager {
     constructor(config?: SessionConfig);
     /** Get or create a session for a conversation */
     getSession(conversationId: string): Session;
+    private appendMessagesToSession;
+    private removeMessagesFromSession;
     /**
      * Enqueue messages for processing in a specific session.
      * Returns a promise that resolves when the handler completes for these messages.
@@ -47,7 +53,7 @@ export declare class SessionManager {
      * - Messages within the same session are serialized (queued).
      * - Messages across different sessions run concurrently up to the concurrency limit.
      */
-    enqueue(conversationId: string, messages: CanonMessage[], handler: SessionHandler): Promise<void>;
+    enqueue(conversationId: string, messages: CanonMessage[], handler: SessionHandler, options?: EnqueueOptions): Promise<void>;
     private drainSession;
     /** Seed a session with historical messages (e.g. fetched from API) */
     seedHistory(conversationId: string, history: CanonMessage[]): void;
@@ -57,6 +63,8 @@ export declare class SessionManager {
     get sessionCount(): number;
     /** Number of queued batches waiting behind the active turn for this conversation. */
     getQueueDepth(conversationId: string): number;
+    /** Drop queued, not-yet-running batches for a conversation. */
+    dropQueued(conversationId: string): CanonMessage[];
     /** Clean up all state */
     destroy(): void;
 }

package/dist/session-manager.js

@@ -50,28 +50,54 @@ export class SessionManager {
         session.lastActiveAt = Date.now();
         return session;
     }
-    /**
-     * Enqueue messages for processing in a specific session.
-     * Returns a promise that resolves when the handler completes for these messages.
-     *
-     * - Messages within the same session are serialized (queued).
-     * - Messages across different sessions run concurrently up to the concurrency limit.
-     */
-    async enqueue(conversationId, messages, handler) {
+    appendMessagesToSession(conversationId, messages) {
         const session = this.getSession(conversationId);
         const seen = this.seenMessages.get(conversationId);
-        // Append new messages using O(1) Set lookup for dedup (#9)
         for (const msg of messages) {
             if (!seen.has(msg.id)) {
                 seen.add(msg.id);
                 session.messages.push(msg);
             }
         }
-        // Trim to context limit (keep most recent)
         if (session.messages.length > this.contextLimit) {
             session.messages = session.messages.slice(-this.contextLimit);
+            const retainedIds = new Set(session.messages.map((message) => message.id));
+            for (const id of Array.from(seen)) {
+                if (!retainedIds.has(id)) {
+                    seen.delete(id);
+                }
+            }
         }
         session.lastActiveAt = Date.now();
+        return session;
+    }
+    removeMessagesFromSession(conversationId, messages) {
+        if (messages.length === 0)
+            return;
+        const session = this.sessions.get(conversationId);
+        const seen = this.seenMessages.get(conversationId);
+        if (!session && !seen)
+            return;
+        const droppedIds = new Set(messages.map((message) => message.id));
+        if (session) {
+            session.messages = session.messages.filter((message) => !droppedIds.has(message.id));
+        }
+        if (seen) {
+            for (const id of droppedIds) {
+                seen.delete(id);
+            }
+        }
+    }
+    /**
+     * Enqueue messages for processing in a specific session.
+     * Returns a promise that resolves when the handler completes for these messages.
+     *
+     * - Messages within the same session are serialized (queued).
+     * - Messages across different sessions run concurrently up to the concurrency limit.
+     */
+    async enqueue(conversationId, messages, handler, options = {}) {
+        const session = this.getSession(conversationId);
+        session.lastActiveAt = Date.now();
         return new Promise((resolve, reject) => {
             // Add to this session's queue
             let queue = this.queues.get(conversationId);
@@ -79,12 +105,18 @@ export class SessionManager {
                 queue = [];
                 this.queues.set(conversationId, queue);
             }
-            queue.push({ messages, resolve, reject });
+            const batch = { messages, handler, resolve, reject };
+            if (options.toFront) {
+                queue.unshift(batch);
+            }
+            else {
+                queue.push(batch);
+            }
             // Try to drain
-            this.drainSession(conversationId, handler);
+            this.drainSession(conversationId);
         });
     }
-    drainSession(conversationId, handler) {
+    drainSession(conversationId) {
         // Already processing this session — the current run will pick up queued items
         if (this.processing.has(conversationId))
             return;
@@ -104,8 +136,8 @@ export class SessionManager {
             this.queues.delete(conversationId);
         this.activeCount++;
         this.processing.add(conversationId);
-        const session = this.getSession(conversationId);
-        handler(session, item.messages)
+        const session = this.appendMessagesToSession(conversationId, item.messages);
+        item.handler(session, item.messages)
             .then(() => item.resolve())
             .catch((err) => item.reject(err))
             .finally(() => {
@@ -114,7 +146,7 @@ export class SessionManager {
             // Continue draining this session if more items queued
             const remaining = this.queues.get(conversationId);
             if (remaining && remaining.length > 0) {
-                this.drainSession(conversationId, handler);
+                this.drainSession(conversationId);
             }
             // Unpark the next pending session.
             // Use Set iteration + explicit delete to get the correct conversation ID
@@ -122,7 +154,7 @@ export class SessionManager {
             if (this.pending.size > 0) {
                 const nextId = this.pending.values().next().value;
                 this.pending.delete(nextId);
-                this.drainSession(nextId, handler);
+                this.drainSession(nextId);
             }
         });
     }
@@ -167,6 +199,20 @@ export class SessionManager {
     getQueueDepth(conversationId) {
         return this.queues.get(conversationId)?.length ?? 0;
     }
+    /** Drop queued, not-yet-running batches for a conversation. */
+    dropQueued(conversationId) {
+        const queue = this.queues.get(conversationId);
+        if (!queue || queue.length === 0)
+            return [];
+        this.queues.delete(conversationId);
+        this.pending.delete(conversationId);
+        const droppedMessages = queue.flatMap((item) => item.messages);
+        this.removeMessagesFromSession(conversationId, droppedMessages);
+        for (const item of queue) {
+            item.resolve();
+        }
+        return droppedMessages;
+    }
     /** Clean up all state */
     destroy() {
         if (this.sweepTimer) {

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, CreateWorkSessionOptions, SendMessageOptions, UpdateWorkSessionConversationOptions } from '@canonmsg/core';
+import type { AddMemberResult, CanonMessage, CanonConversation, CanonRuntimeActionDispatch, CreateWorkSessionOptions, SendMessageOptions, UpdateWorkSessionConversationOptions } from '@canonmsg/core';
 import type { MaterializeMediaOptions, MaterializedCanonAttachment, ReplyWithFileOptions, UploadMediaFileOptions } from './media.js';
 export interface ProgressMessageOptions extends SendMessageOptions {
     /**
@@ -90,6 +90,8 @@ export interface MessageHandlerContext {
     session?: SessionInfo;
     /** Turn lifecycle helpers for live-work rendering and progress reporting. */
     turn?: TurnController;
+    /** Aborted when Canon sends an interrupt/stop signal for this active turn. */
+    abortSignal: AbortSignal;
 }
 export type MessageHandler = (ctx: MessageHandlerContext) => Promise<void>;
 export interface SessionOptions {
@@ -103,6 +105,21 @@ export interface SessionOptions {
     idleTimeoutMs?: number;
 }
 export type DeliveryMode = 'auto' | 'sse';
+export type RuntimeSignalType = Extract<CanonRuntimeActionDispatch, {
+    kind: 'signal';
+}>['signal'];
+export interface RuntimeSignalContext {
+    conversationId: string;
+    signal: RuntimeSignalType;
+    updatedAt?: number;
+    abortSignal?: AbortSignal;
+    droppedMessageIds: string[];
+}
+export type RuntimeSignalHandler = (context: RuntimeSignalContext) => void | Promise<void>;
+export interface RuntimeControlHandlers {
+    onInterrupt?: RuntimeSignalHandler;
+    onStopAndDrop?: RuntimeSignalHandler;
+}
 export interface CanonAgentOptions {
     apiKey: string;
     baseUrl?: string;
@@ -119,6 +136,8 @@ export interface CanonAgentOptions {
     clientType?: import('@canonmsg/core').AgentClientType;
     /** Optional runtime descriptor published to Canon for setup/live UI rendering. */
     runtimeDescriptor?: import('@canonmsg/core').CanonRuntimeDescriptor;
+    /** Optional Canon runtime signal handlers. Enables interrupt controls when provided. */
+    runtimeControls?: RuntimeControlHandlers;
     /**
      * Enable RTDB session-state reporting. Off by default.
      * Turn-state reporting is automatic while handlers run.
@@ -153,6 +172,6 @@ export type ReachOutResult = {
 export interface ReachOutOptions {
     /** Optional first message to send when admission is `allowed`. */
     text?: string;
-    /** Optional message to attach to the contact request when admission is `request-required`. */
+    /** Optional contact-request note. Defaults to `text` when admission is `request-required`. */
     requestMessage?: string;
 }

package/package.json

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