@canonmsg/agent-sdk 11.0.1 → 11.0.2

package/dist/attached-session.js

@@ -45,7 +45,7 @@ export function createCanonAttachedSession(options) {
     let recoveryPromise;
     let nativeReconcilePromise;
     const tasks = new Set();
-    const receiving = new Set();
+    const receiving = new Map();
     const reportedHistory = new Set();
     let publicationFailed = false;
     let historyIncomplete = false;
@@ -84,7 +84,10 @@ export function createCanonAttachedSession(options) {
     const transcriptPublisher = createCanonAttachedSessionPublisher(client, binding);
     const core = createAttachedNativeSession({
         binding, store: options.store, adapter: options.native,
-        beforeNativeSubmit: (input) => endpoint.claimInbound(`message:${binding.conversationId}:${input.messageId}`),
+        submitNative: (input, submit) => {
+            const handoff = receiving.get(input.messageId);
+            return handoff ? endpoint.startInbound(handoff, submit) : Promise.resolve({ status: 'unavailable' });
+        },
         isPublicationReady: () => options.transport?.isRouteActive?.(binding.conversationId) !== false,
         publisher: {
             prepare(input) {
@@ -194,11 +197,11 @@ export function createCanonAttachedSession(options) {
         }
         return true;
     }
-    async function receive(payload) {
+    async function receive(payload, handoff) {
         if (!running || stopped || payload.conversationId !== binding.conversationId)
-            return;
+            return 'deferred';
         if (options.transport?.isRouteActive?.(binding.conversationId) === false)
-            return;
+            return 'deferred';
         const message = payload.message;
         if (message.senderId === binding.agentId || core.hasCanonMessage(message.id)
             || core.isBeforeCanonBaseline(message.id, message.createdAt ?? '') || receiving.has(message.id))
@@ -208,7 +211,7 @@ export function createCanonAttachedSession(options) {
             emit({ status: 'blocked', reason: 'invalid-provenance', messageId: message.id });
             return;
         }
-        receiving.add(message.id);
+        receiving.set(message.id, handoff);
         try {
             if (payload.turnDispatch?.kind !== 'run_turn') {
                 await core.recordSkippedCanonMessage(message.id, 'not-dispatched');
@@ -240,12 +243,10 @@ export function createCanonAttachedSession(options) {
             });
             // A conclusive provider acknowledgement settles command delivery. Native
             // turn progress and transcript correlation remain in the provider journal.
-            const inputId = `message:${binding.conversationId}:${message.id}`;
-            if (result.status === 'uncertain' && result.messageId === message.id) {
-                await endpoint.setInboundState(inputId, 'uncertain', 'native-reconciliation-required');
-            }
-            else if (!(result.status === 'not_submitted' && result.reason === 'This input already has another execution owner.')) {
-                await endpoint.setInboundState(inputId, 'settled', `native-${result.status}`);
+            if (result.status === 'deferred')
+                return 'deferred';
+            if (!(result.status === 'uncertain' && result.messageId === message.id)) {
+                await handoff.settle(`native-${result.status}`);
             }
             if (stopped)
                 return;
@@ -430,20 +431,32 @@ export function createCanonAttachedSession(options) {
             running = true;
             inbound = endpoint.acceptInbound({ kind: 'message.created', conversationId: binding.conversationId,
                 offer: async (event) => {
-                    if (!running || stopped || options.transport?.isRouteActive?.(binding.conversationId) === false) {
-                        await endpoint.setInboundState(event.id, 'deferred', 'attachment-not-ready');
+                    const handoff = await endpoint.acquireInbound(event.id);
+                    if (!handoff)
                         return;
-                    }
-                    const payload = event.data;
-                    if (core.getState().pendingSourceMessageId === payload.message.id && core.getState().status === 'uncertain') {
-                        await endpoint.setInboundState(event.id, 'uncertain', 'native-reconciliation-required');
-                        return;
-                    }
-                    await receive(payload);
-                    const record = await endpoint.getInbound(event.id);
-                    if (record && record.state !== 'uncertain' && record.state !== 'settled') {
-                        await endpoint.setInboundState(event.id, 'settled', 'native-input-reviewed');
-                    }
+                    // The handoff owns deduplication while Core decides busy/accepted.
+                    // Do not block the inbox pump on an external provider acknowledgement.
+                    const received = (async () => {
+                        try {
+                            if (!running || stopped || options.transport?.isRouteActive?.(binding.conversationId) === false)
+                                return;
+                            const payload = event.data;
+                            if (core.getState().pendingSourceMessageId === payload.message.id && core.getState().status === 'uncertain') {
+                                // A recovered native journal can predate endpoint adoption. This
+                                // is provider proof of uncertainty, not permission to resubmit.
+                                await endpoint.setInboundState(event.id, 'uncertain', 'native-reconciliation-required');
+                                return;
+                            }
+                            const result = await receive(payload, handoff);
+                            if (result !== 'deferred' && handoff.phase === 'queued') {
+                                await handoff.cancel('native-input-reviewed');
+                            }
+                        }
+                        finally {
+                            await handoff.release('attached-offer-finished');
+                        }
+                    })();
+                    track(received, 'receive');
                 }, onError: (error) => report(error, 'inbound-recovery') });
             inbound.start();
             const handler = {
@@ -527,6 +540,10 @@ export function createCanonAttachedSession(options) {
             return stopPromise;
         stopped = true;
         running = false;
+        for (const handoff of receiving.values()) {
+            // Register release before waiting for the pending native submission.
+            track(handoff.release('attachment-closed'), 'release-inbound');
+        }
         if (timer)
             clearInterval(timer);
         stream?.stop();

package/dist/canon-agent.d.ts

@@ -87,6 +87,7 @@ export declare class CanonAgent {
     private runtimeStatePublisher;
     private rtdbHandle;
     private controlPoller;
+    private readonly activeInbound;
     private readonly activeAbortControllers;
     private readonly activeTurns;
     private readonly conversationMemberIds;
@@ -221,6 +222,7 @@ export declare class CanonAgent {
     private requireRuntimeStatePublisher;
     private handleMessages;
     private executeHandler;
+    private executeOwnedHandler;
     static register(options: Omit<RegistrationInput, 'baseUrl' | 'developerInfo'> & {
         developerInfo: string;
     } & CanonAgentConnectionOptions): Promise<{

package/dist/canon-agent.js

@@ -1,6 +1,7 @@
 import { ApprovalManager, RuntimeRequestManager, runtimeInputDescriptor, runtimeCardDescriptor, CanonClient, ControlChannelPoller, buildCanonTurnContextV2, buildCanonGroupContext, buildParticipationHistorySnapshot, createTurnOutputController, createRuntimeStatePublisher, createRuntimeHeartbeat, createTypingStatusPublisher, diffCanonMemberIds, FINAL_MESSAGE_HANDOFF_MS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildRuntimeCardOutcome, buildRuntimeInputOutcome, initRTDBAuth, isChunkedSendMessageError, isPendingCanonOperation, normalizeRuntimeCommandDescriptors, normalizeTurnMetadata, normalizeTurnVerbosityConversationType, reportNoReplyOutcome, hydrateCanonReplyContext, resolveMessageActiveSelfContextId, resolveRuntimeProvenance, resolveTurnVerbosity, resolveConversationPolicyScope, selectActiveSelfContexts, renderCanonHostInboundContent, resolveCanonRuntimeConnection, sendMessageWithRetryChunked, shouldPublishTurnTrail, splitTextByUtf8Bytes, verifyCanonRuntimeConnection, } from '@canonmsg/core';
 import { createHash, randomUUID } from 'node:crypto';
 import { Debouncer } from './debouncer.js';
+import { disposeInboundHandoffs, selectInboundHandoffs } from './inbound-handoff.js';
 import { DEFAULT_RUNTIME_INPUT_TIMEOUT_MS, RUNTIME_INPUT_ID_PATTERN, buildRuntimeCardCreateArgs, normalizeResponseUserId, resolveRuntimeCardRouting, } from './runtime-card.js';
 import { materializeMessageMedia, materializeReplyContextMedia, sendMediaFileMessage, uploadMediaFile, } from './media.js';
 import { SessionManager } from './session-manager.js';
@@ -325,6 +326,7 @@ export class CanonAgent {
     runtimeStatePublisher = null;
     rtdbHandle = null;
     controlPoller = null;
+    activeInbound = new Map();
     activeAbortControllers = new Map();
     activeTurns = new Map();
     conversationMemberIds = new Map();
@@ -628,9 +630,9 @@ export class CanonAgent {
         });
         console.log(`[canon-sdk] Authenticated as ${agentId}`);
         // 2. Wire debouncer to handler
-        this.debouncer.setCallback(async (conversationId, messages, provenanceByMessageId) => {
+        this.debouncer.setCallback(async (conversationId, messages, provenanceByMessageId, handoffs) => {
             this.rememberConversationId(conversationId);
-            await this.handleMessages(conversationId, messages, provenanceByMessageId);
+            await this.handleMessages(conversationId, messages, provenanceByMessageId, handoffs);
         });
         // 3. Fetch conversations (used for delivery mode + session state)
         let conversations = [];
@@ -725,6 +727,9 @@ export class CanonAgent {
         });
         rtm.setMessageDeletedHandler((payload) => {
             this.sessionManager?.dropQueuedMessage(payload.conversationId, payload.messageId);
+            for (const handoffs of this.activeInbound.get(payload.conversationId) ?? []) {
+                void disposeInboundHandoffs(selectInboundHandoffs(handoffs, [payload.messageId]), 'cancel', 'message-deleted');
+            }
         });
         rtm.setConnectionHandlers({
             onConnected: () => {
@@ -868,6 +873,10 @@ export class CanonAgent {
         this.realtimeManager?.stop();
         this.realtimeManager = null;
         this.debouncer.destroy();
+        for (const batches of this.activeInbound.values()) {
+            for (const handoffs of batches)
+                void disposeInboundHandoffs(handoffs, 'release', 'runtime-closed');
+        }
         this.sessionManager?.destroy();
         this.sessionManager = null;
         const heartbeat = this.runtimeHeartbeat;
@@ -1005,7 +1014,8 @@ export class CanonAgent {
         }
         if (this.agentId && !memberIds.includes(this.agentId)) {
             this.cachedConversationIds = this.cachedConversationIds.filter((id) => id !== payload.conversationId);
-            this.abortActiveTurns(payload.conversationId);
+            this.abortActiveTurns(payload.conversationId, false);
+            this.debouncer.dropConversation(payload.conversationId);
             this.sessionManager?.dropQueued(payload.conversationId);
             this.pendingMembershipChanges.delete(payload.conversationId);
         }
@@ -1132,11 +1142,14 @@ export class CanonAgent {
             return;
         const activeTurn = this.firstActiveTurn(conversationId);
         const abortSignal = this.abortActiveTurns(conversationId);
-        const droppedMessages = signal === 'new_session'
+        const debouncedMessages = signal === 'new_session' || signal === 'stop_and_drop'
+            ? this.debouncer.dropConversation(conversationId) : [];
+        const sessionMessages = signal === 'new_session'
             ? this.sessionManager?.resetSession(conversationId) ?? []
             : signal === 'stop_and_drop'
                 ? this.sessionManager?.dropQueued(conversationId) ?? []
                 : [];
+        const droppedMessages = [...debouncedMessages, ...sessionMessages];
         const droppedMessageIds = droppedMessages.map((message) => message.id);
         await Promise.all(droppedMessages.map((message) => {
             if (message.metadata?.inboundDisposition !== 'queued')
@@ -1190,7 +1203,12 @@ export class CanonAgent {
             this.typingSignals.clear(conversationId).catch(() => { }),
         ]);
     }
-    abortActiveTurns(conversationId) {
+    abortActiveTurns(conversationId, cancelPreparing = true) {
+        // Membership snapshots may arrive while a newer authoritative refresh is
+        // pending. Only explicit controls discard those still-preparing inputs.
+        for (const handoffs of cancelPreparing ? this.activeInbound.get(conversationId) ?? [] : []) {
+            void disposeInboundHandoffs(handoffs, 'cancel', 'turn-canceled-before-submit');
+        }
         const controllers = this.activeAbortControllers.get(conversationId);
         if (!controllers || controllers.size === 0)
             return undefined;
@@ -1254,81 +1272,79 @@ export class CanonAgent {
         }
         return publisher;
     }
-    async handleMessages(conversationId, messages, provenanceByMessageId) {
+    async handleMessages(conversationId, messages, provenanceByMessageId, handoffs = new Map()) {
         const actionableMessages = this.filterApprovalReplyMessages(conversationId, messages);
         const consumed = messages.filter((message) => !actionableMessages.includes(message));
-        if (consumed.length) {
-            const endpoint = await this.apiClient.getEndpoint();
-            for (const message of consumed) {
-                const id = `message:${conversationId}:${message.id}`;
-                if (await endpoint.getInbound(id))
-                    await endpoint.setInboundState(id, 'settled', 'interaction-consumed');
-            }
-        }
+        void disposeInboundHandoffs(selectInboundHandoffs(handoffs, consumed.map((message) => message.id)), 'cancel', 'interaction-consumed');
         if (actionableMessages.length === 0)
             return;
         messages = actionableMessages;
+        handoffs = selectInboundHandoffs(handoffs, messages.map((message) => message.id));
         if (!this.handler) {
-            const endpoint = await this.apiClient.getEndpoint();
-            for (const message of messages) {
-                const id = `message:${conversationId}:${message.id}`;
-                if (await endpoint.getInbound(id))
-                    await endpoint.setInboundState(id, 'deferred', 'no-handler');
-            }
+            await disposeInboundHandoffs(handoffs, 'release', 'no-handler');
             console.warn(`[canon-sdk] No message handler registered — input for ${conversationId} is deferred. 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);
+        const notification = this.notifyMessageInterrupt(conversationId, abortSignal);
         if (this.sessionManager) {
-            await this.sessionManager.enqueue(conversationId, messages, async (session, newMessages) => {
-                await this.executeHandler(conversationId, newMessages, session, provenanceByMessageId);
-            }, { toFront: shouldInterrupt });
+            await this.sessionManager.enqueue(conversationId, messages, async (session, newMessages, batchHandoffs) => {
+                await this.executeHandler(conversationId, newMessages, session, provenanceByMessageId, batchHandoffs, notification);
+            }, { toFront: shouldInterrupt, handoffs });
         }
         else {
-            await this.executeHandler(conversationId, messages, undefined, provenanceByMessageId);
+            await this.executeHandler(conversationId, messages, undefined, provenanceByMessageId, handoffs, notification);
         }
     }
-    async executeHandler(conversationId, messages, session, provenanceByMessageId) {
-        if (!this.handler)
+    async executeHandler(conversationId, messages, session, provenanceByMessageId, handoffs = new Map(), notification) {
+        const batches = this.activeInbound.get(conversationId) ?? new Set();
+        batches.add(handoffs);
+        this.activeInbound.set(conversationId, batches);
+        try {
+            await notification;
+            await this.executeOwnedHandler(conversationId, messages, session, provenanceByMessageId, handoffs);
+        }
+        finally {
+            batches.delete(handoffs);
+            if (batches.size === 0)
+                this.activeInbound.delete(conversationId);
+            // Queued/deferred inputs go back to the engine's durable retry loop.
+            // Submitted effects cannot be released: failures remain uncertain.
+            await disposeInboundHandoffs(handoffs, 'release', 'sdk-batch-finished');
+        }
+    }
+    async executeOwnedHandler(conversationId, messages, session, provenanceByMessageId, handoffs) {
+        if (!this.handler || messages.length === 0 || handoffs.size !== messages.length
+            || [...handoffs.values()].some((handoff) => handoff.phase !== 'queued'))
             return;
-        // Message rediscovery can precede the SSE roster snapshot after admission.
-        // Refresh before trusting cached exclusion, accepting queued input, or
-        // freezing output policy. Reuse this same snapshot for handler context.
+        // Refresh admission before freezing output policy or constructing context.
         const endpoint = await this.apiClient.getEndpoint();
-        const setInputState = async (state, reason) => {
-            for (const message of messages) {
-                const id = `message:${conversationId}:${message.id}`;
-                if (await endpoint.getInbound(id))
-                    await endpoint.setInboundState(id, state, reason);
-            }
-        };
+        const cancelInputs = (reason) => disposeInboundHandoffs(handoffs, 'cancel', reason);
         let conversation;
         try {
             conversation = await this.apiClient.getConversation(conversationId);
         }
         catch (error) {
-            await setInputState('deferred', 'membership-unavailable');
             console.error(`[canon-sdk] Input deferred until conversation refresh recovers for ${conversationId}:`, error);
             return;
         }
         if (!conversation) {
-            await setInputState('settled', 'conversation-unavailable');
+            await cancelInputs('conversation-unavailable');
             return;
         }
         this.rememberConversationMembers([conversation]);
         const currentMembers = this.conversationMemberIds.get(conversationId);
         if (currentMembers && this.agentId && !currentMembers.includes(this.agentId)) {
-            await setInputState('settled', 'membership-lost');
+            await cancelInputs('membership-lost');
             return;
         }
         this.rememberConversationId(conversationId);
         await this.markQueuedMessagesAccepted(conversationId, messages);
         const acceptedMembers = this.conversationMemberIds.get(conversationId);
         if (acceptedMembers && this.agentId && !acceptedMembers.includes(this.agentId)) {
-            await setInputState('settled', 'membership-lost');
+            await cancelInputs('membership-lost');
             return;
         }
         const turnId = randomUUID();
@@ -1356,6 +1372,9 @@ export class CanonAgent {
         const runtimeState = this.createRuntimeStatePublisher();
         const queueDepth = () => this.sessionManager?.getQueueDepth(conversationId) ?? 0;
         const abortController = new AbortController();
+        abortController.signal.addEventListener('abort', () => {
+            void disposeInboundHandoffs(handoffs, 'cancel', 'turn-canceled-before-submit');
+        }, { once: true });
         const throwIfAborted = () => {
             if (abortController.signal.aborted) {
                 throw createTurnAbortError();
@@ -2196,13 +2215,7 @@ export class CanonAgent {
             // Fence uncertain native/business effects before handing execution out.
             // A crash after this write requires provider/operator reconciliation.
             throwIfAborted();
-            // Every SDK message handler invocation originates in Canon admission. A
-            // restored native queue without its journal must await migration instead
-            // of treating a missing record as permission to execute.
-            const journaled = messages.map((message) => `message:${conversationId}:${message.id}`);
-            if (!journaled.length || !await endpoint.claimInbound(journaled))
-                return;
-            await this.handler({
+            const submission = await endpoint.startInbound([...handoffs.values()], () => this.handler({
                 messages: hydratedMessages,
                 history,
                 replyContext,
@@ -2374,8 +2387,10 @@ export class CanonAgent {
                         }
                     },
                 },
-            });
-            await setInputState('settled', 'handler-completed');
+            }));
+            if (submission.status !== 'submitted')
+                return;
+            await disposeInboundHandoffs(handoffs, 'settle', 'handler-completed');
             // Auto-mark conversation as read after successful processing
             if (this.options.autoMarkRead) {
                 try {

package/dist/debouncer.d.ts

@@ -1,15 +1,18 @@
-import type { CanonMessage, CanonRuntimeProvenance } from '@canonmsg/core';
+import type { CanonMessage, CanonRuntimeProvenance, EndpointInboundHandoff } from '@canonmsg/core';
+import { type InboundHandoffs } from './inbound-handoff.js';
 export declare class Debouncer {
     private debounceMs;
     private pending;
-    private provenanceByMessageId;
+    private provenanceByConversation;
+    private handoffsByConversation;
     private timers;
     private orderedFlags;
     private callback;
     constructor(debounceMs: number);
-    setCallback(cb: (conversationId: string, messages: CanonMessage[], provenanceByMessageId: ReadonlyMap<string, CanonRuntimeProvenance>) => void): void;
-    add(conversationId: string, message: CanonMessage, provenance?: CanonRuntimeProvenance | null): void;
+    setCallback(cb: (conversationId: string, messages: CanonMessage[], provenanceByMessageId: ReadonlyMap<string, CanonRuntimeProvenance>, handoffs: InboundHandoffs) => void | Promise<void>): void;
+    add(conversationId: string, message: CanonMessage, provenance?: CanonRuntimeProvenance | null, handoff?: EndpointInboundHandoff): void;
     removeMessage(conversationId: string, messageId: string): boolean;
     private flush;
+    dropConversation(conversationId: string): CanonMessage[];
     destroy(): void;
 }

package/dist/debouncer.js

@@ -1,7 +1,9 @@
+import { disposeInboundHandoffs } from './inbound-handoff.js';
 export class Debouncer {
     debounceMs;
     pending = new Map();
-    provenanceByMessageId = new Map();
+    provenanceByConversation = new Map();
+    handoffsByConversation = new Map();
     timers = new Map();
     // Track whether each conversation's pending messages are already in sorted
     // order so we can skip the sort on flush when possible (#10)
@@ -13,10 +15,17 @@ export class Debouncer {
     setCallback(cb) {
         this.callback = cb;
     }
-    add(conversationId, message, provenance) {
+    add(conversationId, message, provenance, handoff) {
         const existing = this.pending.get(conversationId) || [];
         if (provenance) {
-            this.provenanceByMessageId.set(message.id, provenance);
+            const provenanceByMessageId = this.provenanceByConversation.get(conversationId) ?? new Map();
+            provenanceByMessageId.set(message.id, provenance);
+            this.provenanceByConversation.set(conversationId, provenanceByMessageId);
+        }
+        if (handoff) {
+            const handoffs = this.handoffsByConversation.get(conversationId) ?? new Map();
+            handoffs.set(message.id, handoff);
+            this.handoffsByConversation.set(conversationId, handoffs);
         }
         // Deduplicate by message ID
         if (!existing.some((m) => m.id === message.id)) {
@@ -50,9 +59,15 @@ export class Debouncer {
         const next = existing.filter((message) => message.id !== messageId);
         if (next.length === existing.length)
             return false;
-        this.provenanceByMessageId.delete(messageId);
+        this.provenanceByConversation.get(conversationId)?.delete(messageId);
+        const handoff = this.handoffsByConversation.get(conversationId)?.get(messageId);
+        if (handoff)
+            void disposeInboundHandoffs(new Map([[messageId, handoff]]), 'cancel', 'message-deleted');
+        this.handoffsByConversation.get(conversationId)?.delete(messageId);
         if (next.length === 0) {
             this.pending.delete(conversationId);
+            this.provenanceByConversation.delete(conversationId);
+            this.handoffsByConversation.delete(conversationId);
             this.orderedFlags.delete(conversationId);
             const timer = this.timers.get(conversationId);
             if (timer)
@@ -75,24 +90,44 @@ export class Debouncer {
             if (!isOrdered) {
                 messages.sort((a, b) => new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime());
             }
-            const provenanceByMessageId = new Map();
-            for (const message of messages) {
-                const provenance = this.provenanceByMessageId.get(message.id);
-                if (provenance) {
-                    provenanceByMessageId.set(message.id, provenance);
-                    this.provenanceByMessageId.delete(message.id);
-                }
+            const provenanceByMessageId = this.provenanceByConversation.get(conversationId) ?? new Map();
+            const handoffs = this.handoffsByConversation.get(conversationId) ?? new Map();
+            this.provenanceByConversation.delete(conversationId);
+            this.handoffsByConversation.delete(conversationId);
+            const failed = async (error) => {
+                await disposeInboundHandoffs(handoffs, 'release', 'dispatch-failed');
+                console.error('[canon-sdk] Inbound dispatch failed:', error);
+            };
+            try {
+                void Promise.resolve(this.callback(conversationId, messages, provenanceByMessageId, handoffs)).catch(failed);
+            }
+            catch (error) {
+                void failed(error);
             }
-            this.callback(conversationId, messages, provenanceByMessageId);
         }
+        else {
+            void disposeInboundHandoffs(this.handoffsByConversation.get(conversationId) ?? new Map(), 'release', 'no-dispatcher');
+            this.provenanceByConversation.delete(conversationId);
+            this.handoffsByConversation.delete(conversationId);
+        }
+    }
+    dropConversation(conversationId) {
+        const messages = this.pending.get(conversationId) ?? [];
+        for (const message of messages)
+            this.removeMessage(conversationId, message.id);
+        return messages;
     }
     destroy() {
+        for (const handoffs of this.handoffsByConversation.values()) {
+            void disposeInboundHandoffs(handoffs, 'release', 'debouncer-closed');
+        }
+        this.handoffsByConversation.clear();
         for (const timer of this.timers.values()) {
             clearTimeout(timer);
         }
         this.timers.clear();
         this.pending.clear();
-        this.provenanceByMessageId.clear();
+        this.provenanceByConversation.clear();
         this.orderedFlags.clear();
     }
 }

package/dist/inbound-handoff.d.ts

@@ -0,0 +1,6 @@
+import type { EndpointInboundHandoff } from '@canonmsg/core';
+/** Message-keyed handles within one conversation, carried with its queue entry. */
+export type InboundHandoffs = ReadonlyMap<string, EndpointInboundHandoff>;
+export declare function selectInboundHandoffs(handoffs: InboundHandoffs, messageIds: readonly string[]): InboundHandoffs;
+/** Calls record intent synchronously, even when a durable claim is awaiting IO. */
+export declare function disposeInboundHandoffs(handoffs: InboundHandoffs, disposition: 'cancel' | 'release' | 'settle', reason: string): Promise<void>;

package/dist/inbound-handoff.js

@@ -0,0 +1,17 @@
+export function selectInboundHandoffs(handoffs, messageIds) {
+    const selected = new Map();
+    for (const id of messageIds) {
+        const handoff = handoffs.get(id);
+        if (handoff)
+            selected.set(id, handoff);
+    }
+    return selected;
+}
+/** Calls record intent synchronously, even when a durable claim is awaiting IO. */
+export async function disposeInboundHandoffs(handoffs, disposition, reason) {
+    const results = await Promise.allSettled([...handoffs.values()].map((handoff) => handoff[disposition](reason)));
+    for (const result of results) {
+        if (result.status === 'rejected')
+            console.error(`[canon-sdk] Inbound ${disposition} failed:`, result.reason);
+    }
+}

package/dist/realtime.js

@@ -98,8 +98,11 @@ export class RealtimeManager {
     }
     async offer(payload) {
         const id = `message:${payload.conversationId}:${payload.message.id}`;
+        const handoff = await this.endpoint.acquireInbound(id);
+        if (!handoff)
+            return;
         if (payload.turnDispatch && payload.turnDispatch.kind !== 'run_turn') {
-            await this.endpoint.setInboundState(id, 'settled', 'observe-only');
+            await handoff.cancel('observe-only');
             return;
         }
         const m = payload.message;
@@ -129,7 +132,7 @@ export class RealtimeManager {
             ...(m.metadata ? { metadata: m.metadata } : {}),
             ...(payload.replyAuthority ? { replyAuthority: payload.replyAuthority } : {}),
         };
-        this.debouncer.add(payload.conversationId, message, payload.provenance ?? null);
+        this.debouncer.add(payload.conversationId, message, payload.provenance ?? null, handoff);
     }
     logSseError(err) {
         const code = err.code;

package/dist/session-manager.d.ts

@@ -1,4 +1,5 @@
 import type { CanonMessage } from '@canonmsg/core';
+import { type InboundHandoffs } from './inbound-handoff.js';
 export interface SessionConfig {
     /** Max messages to retain per session (default: 50) */
     contextLimit?: number;
@@ -17,10 +18,12 @@ export interface Session {
     /** When this session last processed a message */
     lastActiveAt: number;
 }
-type SessionHandler = (session: Session, newMessages: CanonMessage[]) => Promise<void>;
+type SessionHandler = (session: Session, newMessages: CanonMessage[], handoffs: InboundHandoffs) => Promise<void>;
 export interface EnqueueOptions {
     /** Place this batch ahead of other not-yet-running batches. */
     toFront?: boolean;
+    /** Execution receipts carried with this batch, independent of retained history. */
+    handoffs?: InboundHandoffs;
 }
 /**
  * Manages per-conversation sessions with:
@@ -33,6 +36,7 @@ export declare class SessionManager {
     private sessions;
     private queues;
     private activeCount;
+    private destroyed;
     private pending;
     private processing;
     private seenMessages;

package/dist/session-manager.js

@@ -1,3 +1,4 @@
+import { disposeInboundHandoffs, selectInboundHandoffs } from './inbound-handoff.js';
 const DEFAULT_CONTEXT_LIMIT = 50;
 const DEFAULT_CONCURRENCY = 10;
 const DEFAULT_IDLE_TIMEOUT_MS = 60 * 60 * 1000; // 1 hour
@@ -13,6 +14,7 @@ export class SessionManager {
     sessions = new Map();
     queues = new Map();
     activeCount = 0;
+    destroyed = false;
     // Use Set<string> instead of Array for O(1) dedup and correct pop semantics (#1, #2)
     pending = new Set();
     processing = new Set();
@@ -96,6 +98,10 @@ export class SessionManager {
      * - Messages across different sessions run concurrently up to the concurrency limit.
      */
     async enqueue(conversationId, messages, handler, options = {}) {
+        if (this.destroyed) {
+            await disposeInboundHandoffs(options.handoffs ?? new Map(), 'release', 'session-manager-closed');
+            return;
+        }
         const session = this.getSession(conversationId);
         session.lastActiveAt = Date.now();
         return new Promise((resolve, reject) => {
@@ -105,7 +111,7 @@ export class SessionManager {
                 queue = [];
                 this.queues.set(conversationId, queue);
             }
-            const batch = { messages, handler, resolve, reject };
+            const batch = { messages, handler, resolve, reject, handoffs: options.handoffs ?? new Map() };
             if (options.toFront) {
                 queue.unshift(batch);
             }
@@ -118,7 +124,7 @@ export class SessionManager {
     }
     drainSession(conversationId) {
         // Already processing this session — the current run will pick up queued items
-        if (this.processing.has(conversationId))
+        if (this.destroyed || this.processing.has(conversationId))
             return;
         const queue = this.queues.get(conversationId);
         if (!queue || queue.length === 0)
@@ -137,7 +143,7 @@ export class SessionManager {
         this.activeCount++;
         this.processing.add(conversationId);
         const session = this.appendMessagesToSession(conversationId, item.messages);
-        item.handler(session, item.messages)
+        item.handler(session, item.messages, item.handoffs)
             .then(() => item.resolve())
             .catch((err) => item.reject(err))
             .finally(() => {
@@ -205,15 +211,17 @@ export class SessionManager {
         for (const item of queue) {
             const keptMessages = item.messages.filter((message) => {
                 const drop = message.id === messageId;
-                if (drop)
+                if (drop) {
                     droppedMessages.push(message);
+                    void disposeInboundHandoffs(selectInboundHandoffs(item.handoffs, [message.id]), 'cancel', 'message-deleted');
+                }
                 return !drop;
             });
             if (keptMessages.length === 0) {
                 item.resolve();
             }
             else if (keptMessages.length !== item.messages.length) {
-                nextQueue.push({ ...item, messages: keptMessages });
+                nextQueue.push({ ...item, messages: keptMessages, handoffs: selectInboundHandoffs(item.handoffs, keptMessages.map((message) => message.id)) });
             }
             else {
                 nextQueue.push(item);
@@ -241,6 +249,7 @@ export class SessionManager {
         const droppedMessages = queue.flatMap((item) => item.messages);
         this.removeMessagesFromSession(conversationId, droppedMessages);
         for (const item of queue) {
+            void disposeInboundHandoffs(item.handoffs, 'cancel', 'queue-dropped');
             item.resolve();
         }
         return droppedMessages;
@@ -255,6 +264,13 @@ export class SessionManager {
     }
     /** Clean up all state */
     destroy() {
+        this.destroyed = true;
+        for (const queue of this.queues.values()) {
+            for (const item of queue) {
+                void disposeInboundHandoffs(item.handoffs, 'release', 'session-manager-closed');
+                item.resolve();
+            }
+        }
         if (this.sweepTimer) {
             clearInterval(this.sweepTimer);
             this.sweepTimer = null;
@@ -265,6 +281,5 @@ export class SessionManager {
         this.processing.clear();
         this.seenMessages.clear();
         this.seededSessions.clear();
-        this.activeCount = 0;
     }
 }

package/dist/work-session-host.js

@@ -397,11 +397,22 @@ export function createCanonWorkSessionHost(options) {
     }
     async function renew() {
         fence();
-        const conversations = await client.getConversations();
-        for (const room of [...rooms.values()]) {
-            const conversation = conversations.find((entry) => entry.id === room.binding.conversationId);
-            if (!conversation?.memberIds.includes(connection.agentId) || !conversation.memberIds.includes(broker.ownerId))
-                await removeRoom(room.binding.conversationId, true);
+        // Renewal only needs the bound audience. Never enumerate the account's
+        // unrelated rooms, and bound concurrent reads even for a busy host.
+        const boundRooms = [...rooms.values()];
+        for (let offset = 0; offset < boundRooms.length; offset += 8) {
+            fence();
+            const checked = await Promise.all(boundRooms.slice(offset, offset + 8).map(async (room) => ({
+                room, conversation: await client.getConversation(room.binding.conversationId),
+            })));
+            fence();
+            for (const { room, conversation } of checked) {
+                // A stream update may already have removed/replaced this attachment.
+                if (rooms.get(room.binding.conversationId) !== room)
+                    continue;
+                if (!conversation?.memberIds.includes(connection.agentId) || !conversation.memberIds.includes(broker.ownerId))
+                    await removeRoom(room.binding.conversationId, true);
+            }
         }
         // Catalog has its own freshness deadline; it is refreshed independently of public presence.
         const catalog = await options.provider.catalog();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-sdk",
-  "version": "11.0.1",
+  "version": "11.0.2",
   "description": "Canon Agent SDK — build AI agents that participate in Canon conversations",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,7 @@
     "node": ">=22.22.3"
   },
   "dependencies": {
-    "@canonmsg/core": "^13.0.4"
+    "@canonmsg/core": "^13.0.5"
   },
   "publishConfig": {
     "access": "public"