@canonmsg/agent-sdk 0.10.2 → 1.1.0

package/README.md

@@ -12,9 +12,9 @@ const agent = new CanonAgent({
   historyLimit: 30,
 });
 
-agent.on('message', async ({ messages, history, reply }) => {
+agent.on('message', async ({ messages, history, replyFinal }) => {
   const response = await callMyLLM(messages, history);
-  await reply(response);
+  await replyFinal(response);
 });
 
 await agent.start();
@@ -35,13 +35,13 @@ No additional dependencies required — the SDK uses native `fetch` and `Readabl
 | `apiKey` | `string` | **required** | API key obtained after agent registration approval |
 | `baseUrl` | `string` | Canon production URL | Override the API base URL |
 | `streamUrl` | `string` | Canon stream service URL | Override the SSE stream URL |
-| `deliveryMode` | `'auto' \| 'sse' \| 'polling'` | `'auto'` | How the SDK receives new messages |
-| `pollingIntervalMs` | `number` | `3000` | Polling interval in milliseconds (polling mode only) |
+| `deliveryMode` | `'auto' \| 'sse'` | `'auto'` | How the SDK receives new messages |
 | `debounceMs` | `number` | `2000` | Batching window for incoming messages per conversation |
 | `historyLimit` | `number` | `50` | Number of historical messages to fetch (max 100) |
 | `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
@@ -89,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.
@@ -110,11 +133,11 @@ Current rules of thumb:
 
 ## Delivery Modes
 
-The SDK supports three delivery modes for receiving messages:
+The SDK supports SSE-backed delivery modes for receiving messages:
 
 ### `auto` (default)
 
-Uses `sse`. Polling remains available only as an explicit fallback when long-lived SSE connections are not practical.
+Uses `sse`.
 
 ### `sse`
 
@@ -122,23 +145,16 @@ Connects to Canon's SSE stream service for instant message delivery. A single co
 
 Best for: agents in a small-to-medium number of active conversations where low latency matters.
 
-### `polling`
-
-Periodically calls the REST API to discover new messages. Latency is bounded by `pollingIntervalMs`.
-
-Best for: agents in many conversations, or environments where long-lived connections are not practical.
-
 ## Message Handler
 
 The `message` event handler receives a context object with:
 
 | Field | Type | Description |
 |---|---|---|
-| `messages` | `SDKMessage[]` | New messages in this batch (debounced, sorted by time) |
-| `history` | `SDKMessage[]` | Last N messages before these new ones |
+| `messages` | `CanonMessage[]` | New messages in this batch (debounced, sorted by time) |
+| `history` | `CanonMessage[]` | Last N messages before these new ones |
 | `conversationId` | `string` | The conversation these messages belong to |
-| `conversation` | `SDKConversation` | Full conversation metadata |
-| `reply` | `(text: string, options?) => Promise<{ messageId: string }>` | Convenience alias for `replyFinal` |
+| `conversation` | `CanonConversation` | Full conversation metadata |
 | `replyFinal` | `(text: string, options?) => Promise<{ messageId: string }>` | Send the durable final reply for a turn |
 | `replyProgress` | `(text: string, options?) => Promise<{ turnId: string; durable: boolean; messageId: string \| null }>` | Update the live turn progress; add `durable: true` to also persist it |
 | `agent` | `AgentContext` | Trusted Canon agent identity and access context |
@@ -255,9 +271,9 @@ The SDK exports `CanonApiError` for typed error handling:
 ```typescript
 import { CanonAgent, CanonApiError } from '@canonmsg/agent-sdk';
 
-agent.on('message', async ({ messages, reply }) => {
+agent.on('message', async ({ messages, replyFinal }) => {
   try {
-    await reply('Hello!');
+    await replyFinal('Hello!');
   } catch (err) {
     if (err instanceof CanonApiError) {
       console.error(`API error ${err.status}: ${err.message}`);

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
@@ -23,7 +23,6 @@ export declare class CanonAgent {
     private apiClient;
     private authManager;
     private debouncer;
-    private pollingManager;
     private realtimeManager;
     private sessionManager;
     private handler;
@@ -31,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. */
@@ -41,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
@@ -87,10 +93,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,9 +1,8 @@
-import { CanonClient, createRuntimeStatePublisher, FINAL_MESSAGE_HANDOFF_MS, initRTDBAuth, mergeWorkSessionContexts, } from '@canonmsg/core';
+import { CanonClient, createRuntimeStatePublisher, FINAL_MESSAGE_HANDOFF_MS, initRTDBAuth, rtdbRead, rtdbWrite, mergeWorkSessionContexts, normalizeTurnMetadata, } 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 { PollingManager } from './polling.js';
 import { SessionManager } from './session-manager.js';
 const AGENT_RUNTIME_HEARTBEAT_MS = 30_000;
 const SDK_RUNTIME_CAPABILITIES = {
@@ -19,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));
 }
@@ -27,7 +46,6 @@ export class CanonAgent {
     apiClient;
     authManager;
     debouncer;
-    pollingManager = null;
     realtimeManager = null;
     sessionManager = null;
     handler = null;
@@ -35,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. */
@@ -45,11 +65,13 @@ 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',
             deliveryMode: 'auto',
-            pollingIntervalMs: 3000,
             debounceMs: 2000,
             historyLimit: 50,
             autoMarkRead: true,
@@ -76,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') {
@@ -94,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;
     }
     /**
@@ -170,6 +214,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)
@@ -187,6 +232,9 @@ export class CanonAgent {
             mode = 'sse';
             console.log(`[canon-sdk] Auto-selected ${mode} mode (${conversations.length} conversations)`);
         }
+        if (mode !== 'sse') {
+            throw new Error(`Unsupported deliveryMode: ${mode}. Use 'auto' or 'sse'.`);
+        }
         // 3b. Fetch agent context (identity, owner, access level)
         try {
             this.agentContext = await this.apiClient.getAgentMe();
@@ -208,42 +256,37 @@ 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
-        if (mode === 'sse' || mode === 'realtime') {
-            const { RealtimeManager } = await import('./realtime.js');
-            const rtm = new RealtimeManager(this.options.apiKey, this.debouncer, agentId, this.options.streamUrl, this.apiClient);
-            rtm.setOnAgentContext((ctx) => {
-                this.agentContext = ctx;
-            });
-            rtm.setContactRequestHandlers({
-                onContactRequest: (request) => {
-                    void this.handleContactRequestEvent(this.contactRequestHandler, request);
-                },
-                onContactApproved: (request) => {
-                    void this.handleContactRequestEvent(this.contactApprovedHandler, request);
-                },
-            });
-            rtm.setContactGraphHandlers({
-                onContactAdded: (payload) => {
-                    void this.handleContactGraphEvent(this.contactAddedHandler, payload);
-                },
-                onContactRemoved: (payload) => {
-                    void this.handleContactGraphEvent(this.contactRemovedHandler, payload);
-                },
-            });
-            rtm.setConnectionHandlers({
-                onConnected: () => this.startRuntimeHeartbeat(),
-                onDisconnected: () => this.stopRuntimeHeartbeat(),
-            });
-            this.realtimeManager = rtm;
-            await rtm.start();
-            console.log('[canon-sdk] SSE stream started');
-        }
-        else {
-            this.pollingManager = new PollingManager(this.apiClient, this.debouncer, agentId, this.options.pollingIntervalMs, () => this.startRuntimeHeartbeat(), () => this.stopRuntimeHeartbeat());
-            await this.pollingManager.start();
-            console.log(`[canon-sdk] Polling started (interval: ${this.options.pollingIntervalMs}ms)`);
-        }
+        const { RealtimeManager } = await import('./realtime.js');
+        const rtm = new RealtimeManager(this.options.apiKey, this.debouncer, agentId, this.options.streamUrl, this.apiClient);
+        rtm.setOnAgentContext((ctx) => {
+            this.agentContext = ctx;
+        });
+        rtm.setContactRequestHandlers({
+            onContactRequest: (request) => {
+                void this.handleContactRequestEvent(this.contactRequestHandler, request);
+            },
+            onContactApproved: (request) => {
+                void this.handleContactRequestEvent(this.contactApprovedHandler, request);
+            },
+        });
+        rtm.setContactGraphHandlers({
+            onContactAdded: (payload) => {
+                void this.handleContactGraphEvent(this.contactAddedHandler, payload);
+            },
+            onContactRemoved: (payload) => {
+                void this.handleContactGraphEvent(this.contactRemovedHandler, payload);
+            },
+        });
+        rtm.setConnectionHandlers({
+            onConnected: () => this.startRuntimeHeartbeat(),
+            onDisconnected: () => this.stopRuntimeHeartbeat(),
+        });
+        this.realtimeManager = rtm;
+        await rtm.start();
+        console.log('[canon-sdk] SSE stream started');
     }
     async createConversation(options) {
         return this.apiClient.createConversation(options);
@@ -304,6 +347,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) {
@@ -317,19 +361,61 @@ export class CanonAgent {
             }
         }
         await this.clearAgentRuntime();
-        this.pollingManager?.stop();
         this.realtimeManager?.stop();
         this.sessionManager?.destroy();
         this.authManager.destroy();
         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() {
@@ -351,6 +437,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;
@@ -365,10 +558,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);
@@ -384,6 +581,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;
@@ -393,7 +594,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' } }
@@ -591,7 +792,6 @@ export class CanonAgent {
                 history,
                 conversationId,
                 conversation,
-                reply: replyFinal,
                 replyFinal,
                 replyProgress,
                 deleteMessage,
@@ -607,6 +807,7 @@ export class CanonAgent {
                 agent,
                 workSession,
                 activeWorkSessions,
+                abortSignal: abortController.signal,
                 media: {
                     materialize: (message = hydratedMessages[hydratedMessages.length - 1], options) => {
                         if (!message)
@@ -680,6 +881,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/index.d.ts

@@ -7,4 +7,4 @@ export { getCodexImagePath, getMessageAttachments, inferUploadMimeType, isAnthro
 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 { SDKMessage, SDKConversation, CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, ContactRequestHandler, MessageHandler, MessageHandlerContext, ProgressMessageOptions, ProgressMessageResult, ReachOutOptions, ReachOutResult, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';
+export type { CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, ContactRequestHandler, MessageHandler, MessageHandlerContext, ProgressMessageOptions, ProgressMessageResult, ReachOutOptions, ReachOutResult, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';

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/turn-filter.js

@@ -4,15 +4,6 @@ function normalizeRuntimeTurnState(value) {
     if (turnState) {
         return { state: turnState.state };
     }
-    if (!value || typeof value !== 'object')
-        return null;
-    const state = value.state;
-    if (state === 'running') {
-        return { state: 'streaming' };
-    }
-    if (state === 'requires_action') {
-        return { state: 'waiting_input' };
-    }
     return null;
 }
 export async function shouldDispatchInboundMessage(conversationId, agentId, message, options) {

package/dist/types.d.ts

@@ -1,8 +1,6 @@
 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 type SDKMessage = CanonMessage;
-export type SDKConversation = CanonConversation;
 export interface ProgressMessageOptions extends SendMessageOptions {
     /**
      * Persist the progress update to Firestore.
@@ -23,7 +21,7 @@ export interface SessionInfo {
     /** Session ID (= conversationId) */
     id: string;
     /** All accumulated messages for this conversation (within the context limit), oldest first */
-    messages: SDKMessage[];
+    messages: CanonMessage[];
     /** Arbitrary per-session state the agent can read/write across handler calls */
     metadata: Record<string, unknown>;
     queueDepth?: number;
@@ -37,13 +35,10 @@ export interface TurnController {
     setWaitingInput: (text?: string) => Promise<void>;
 }
 export interface MessageHandlerContext {
-    messages: SDKMessage[];
-    history: SDKMessage[];
+    messages: CanonMessage[];
+    history: CanonMessage[];
     conversationId: string;
-    conversation: SDKConversation;
-    reply: (text: string, options?: SendMessageOptions) => Promise<{
-        messageId: string;
-    }>;
+    conversation: CanonConversation;
     replyFinal: (text: string, options?: SendMessageOptions) => Promise<{
         messageId: string;
     }>;
@@ -82,7 +77,7 @@ export interface MessageHandlerContext {
     activeWorkSessions?: import('@canonmsg/core').CanonWorkSessionContext[];
     /** Canon-managed local media access for the current conversation. */
     media: {
-        materialize: (message?: SDKMessage, options?: Omit<MaterializeMediaOptions, 'agentId' | 'conversationId' | 'messageId'>) => Promise<MaterializedCanonAttachment[]>;
+        materialize: (message?: CanonMessage, options?: Omit<MaterializeMediaOptions, 'agentId' | 'conversationId' | 'messageId'>) => Promise<MaterializedCanonAttachment[]>;
         uploadFile: (filePath: string, options?: UploadMediaFileOptions) => Promise<{
             url: string;
             attachment: import('@canonmsg/core').MediaAttachment;
@@ -95,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 {
@@ -107,14 +104,28 @@ export interface SessionOptions {
     /** Evict idle sessions after this many ms (default: 3600000 = 1h) */
     idleTimeoutMs?: number;
 }
-export type DeliveryMode = 'auto' | 'sse' | 'realtime' | 'polling';
+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;
     streamUrl?: string;
-    /** `auto` now resolves to SSE; use `polling` only as an explicit fallback. */
+    /** `auto` resolves to SSE. */
     deliveryMode?: DeliveryMode;
-    pollingIntervalMs?: number;
     debounceMs?: number;
     historyLimit?: number;
     /** Automatically mark conversations as read when handling messages (default: true) */
@@ -125,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.

package/package.json

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

package/dist/polling.d.ts

@@ -1,18 +0,0 @@
-import { CanonClient } from '@canonmsg/core';
-import { Debouncer } from './debouncer.js';
-export declare class PollingManager {
-    private apiClient;
-    private debouncer;
-    private agentId;
-    private pollingIntervalMs;
-    private onHealthy;
-    private onUnhealthy;
-    private lastSeenTimestamps;
-    private pollTimer;
-    private running;
-    constructor(apiClient: CanonClient, debouncer: Debouncer, agentId: string, pollingIntervalMs: number, onHealthy?: () => void, onUnhealthy?: () => void);
-    start(): Promise<void>;
-    private poll;
-    private findActiveConversations;
-    stop(): void;
-}

package/dist/polling.js

@@ -1,99 +0,0 @@
-import { buildParticipationHistorySnapshots } from './policy-history.js';
-import { shouldDispatchInboundMessage } from './turn-filter.js';
-export class PollingManager {
-    apiClient;
-    debouncer;
-    agentId;
-    pollingIntervalMs;
-    onHealthy;
-    onUnhealthy;
-    lastSeenTimestamps = new Map();
-    pollTimer = null;
-    running = false;
-    constructor(apiClient, debouncer, agentId, pollingIntervalMs, onHealthy, onUnhealthy) {
-        this.apiClient = apiClient;
-        this.debouncer = debouncer;
-        this.agentId = agentId;
-        this.pollingIntervalMs = pollingIntervalMs;
-        this.onHealthy = onHealthy ?? null;
-        this.onUnhealthy = onUnhealthy ?? null;
-    }
-    async start() {
-        this.running = true;
-        // Initialize: mark current time as baseline (only respond to messages after start)
-        const now = Date.now();
-        const conversations = await this.apiClient.getConversations();
-        for (const convo of conversations) {
-            this.lastSeenTimestamps.set(convo.id, now);
-        }
-        this.onHealthy?.();
-        // Start polling
-        this.pollTimer = setInterval(() => this.poll(), this.pollingIntervalMs);
-    }
-    async poll() {
-        if (!this.running)
-            return;
-        try {
-            const conversations = await this.apiClient.getConversations();
-            this.onHealthy?.();
-            const activeConvos = this.findActiveConversations(conversations);
-            await Promise.all(activeConvos.map(async (convo) => {
-                try {
-                    const page = await this.apiClient.getMessagesPage(convo.id, 50);
-                    const messages = page.messages;
-                    const participationHistory = buildParticipationHistorySnapshots(messages, this.agentId);
-                    // Filter to only new messages (after lastSeen, not from self)
-                    const lastSeen = this.lastSeenTimestamps.get(convo.id) || 0;
-                    const newMessages = messages.filter((m) => {
-                        const msgTime = new Date(m.createdAt).getTime();
-                        return msgTime > lastSeen && m.senderId !== this.agentId;
-                    });
-                    const dispatchable = await Promise.all(newMessages.map(async (message) => ({
-                        message,
-                        allow: await shouldDispatchInboundMessage(convo.id, this.agentId, message, {
-                            conversationType: convo.type,
-                            behavior: page.behavior,
-                            recentHumanCount: participationHistory.get(message.id)?.recentHumanCount,
-                            consecutiveAgentTurns: participationHistory.get(message.id)?.consecutiveAgentTurns,
-                            currentAgentStreakStartedByHuman: participationHistory.get(message.id)?.currentAgentStreakStartedByHuman,
-                        }),
-                    })));
-                    for (const msg of dispatchable.filter((entry) => entry.allow).map((entry) => entry.message)) {
-                        this.debouncer.add(convo.id, msg);
-                    }
-                    // Update lastSeen to latest message timestamp
-                    if (messages.length > 0) {
-                        const latestTime = Math.max(...messages.map((m) => new Date(m.createdAt).getTime()));
-                        this.lastSeenTimestamps.set(convo.id, latestTime);
-                    }
-                }
-                catch (err) {
-                    console.error(`[canon-sdk] Failed to fetch messages for ${convo.id}:`, err);
-                }
-            }));
-        }
-        catch (err) {
-            this.onUnhealthy?.();
-            console.error('[canon-sdk] Polling error:', err);
-        }
-    }
-    findActiveConversations(conversations) {
-        return conversations.filter((convo) => {
-            if (!convo.lastMessage)
-                return false;
-            // Skip if agent was last sender
-            if (convo.lastMessage.senderId === this.agentId)
-                return false;
-            const lastMsgTime = new Date(convo.lastMessage.timestamp).getTime();
-            const lastSeen = this.lastSeenTimestamps.get(convo.id) || 0;
-            return lastMsgTime > lastSeen;
-        });
-    }
-    stop() {
-        this.running = false;
-        if (this.pollTimer) {
-            clearInterval(this.pollTimer);
-            this.pollTimer = null;
-        }
-    }
-}