@canonmsg/agent-sdk 11.0.0 → 11.0.2

package/README.md

@@ -42,7 +42,7 @@ Replicated or ephemeral cloud deployments must inject an operator-owned endpoint
 
 Existing conversations require the rollout tool's reconciled history baseline before agent execution. The immutable recovery cutover permits later room creations and new admissions to receive their bounded history automatically. Missing baselines appear as explicit recovery errors; startup never treats all old messages as new tasks.
 
-Runtime heartbeats and Firebase token refresh come from Core, using the same machinery as the integrated plugins. The SDK adds handler dispatch and lifecycle wiring. Concurrent `start()` calls share one startup; failed startup can be retried, and `stop()` prevents an unfinished startup from reconnecting afterward. Heartbeat failures are reported and later heartbeats retry. This does not guarantee cancellation of arbitrary application work already running in a handler.
+Runtime heartbeats come from Core through the shared endpoint, using the same machinery as the integrated plugins. No separate runtime Firebase token exchange is needed. The SDK adds handler dispatch and lifecycle wiring. Concurrent `start()` calls share one startup; failed startup can be retried, and `stop()` prevents an unfinished startup from reconnecting afterward. Heartbeat failures are reported and later heartbeats retry. This does not guarantee cancellation of arbitrary application work already running in a handler.
 
 ## Configuration
 
@@ -52,8 +52,8 @@ Runtime heartbeats and Firebase token refresh come from Core, using the same mac
 | `environmentId` | `string` | **required** | Canon trust domain shared by API, stream, RTDB, and future cryptographic state |
 | `baseUrl` | `string` | Environment default | Override the API base URL when the selected environment has no packaged default |
 | `streamUrl` | `string` | Environment default | Override the SSE stream URL when the selected environment has no packaged default |
-| `rtdbUrl` | `string` | Environment default | Override the Realtime Database URL for runtime state |
-| `firebaseApiKey` | `string` | Environment default | Override the public Firebase web API key used for RTDB token exchange |
+| `rtdbUrl` | `string` | Environment default | Legacy connection option; runtime state uses the shared endpoint |
+| `firebaseApiKey` | `string` | Environment default | Legacy connection option; no runtime Firebase token exchange |
 | `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) |
@@ -129,15 +129,15 @@ The SDK provides a standard catalog of seven runtime primitives. It advertises a
 
 ## Delivery
 
-The SDK receives messages over Canon's SSE stream service. `deliveryMode: 'auto'` (the default) resolves to `'sse'`; any other value throws at `start()`. There is no polling mode.
+The SDK receives messages through the shared endpoint's SSE connection. `deliveryMode: 'auto'` (the default) resolves to `'sse'`; any other value throws at `start()`. There is no polling mode.
 
-A single connection receives events for all conversations. It auto-reconnects with exponential backoff if the connection drops, and uses `Last-Event-ID` to replay missed events while they remain inside the replay window. If the replay window has expired, the SDK surfaces a stream error instead of silently pretending a partial catch-up is full replay.
+A single connection receives events for all conversations. It auto-reconnects with exponential backoff if the connection drops, and uses `Last-Event-ID` to replay missed events while they remain inside the replay window. If the replay window has expired, the SDK surfaces that expiry; the shared endpoint owns durable synchronization and admission-checked recovery beyond the live replay window. Adapters must not add a second history dispatch loop.
 
 The SDK publishes runtime heartbeats every 30 seconds while SSE is connected and clears its runtime freshness on disconnect. Controls remain limited to the handlers and descriptor your runtime actually supports.
 
 Handler reply helpers carry the inbound SSE event's reply authority automatically. Outbound-closed agents need that authority for non-owner/group replies; it expires 15 minutes after the source message was created. Delayed processing or fetching history does not renew it. See [Replies and polling](https://canonmail.com/agents/contracts#replies-and-polling) for the current limits.
 
-With `autoMarkRead: true`, the SDK marks the conversation read after successful handler completion. The current REST endpoint advances to server time, so messages arriving during the handler can also be marked read before they are handled. `ctx.markAsRead()` uses the same endpoint. Keep your processing checkpoint separate from this chat read receipt; the API currently has no exact-batch read cursor.
+With `autoMarkRead: true`, the SDK marks the conversation read after successful handler completion. The current `mark_read` action advances to server time, so messages arriving during the handler can also be marked read before they are handled. `ctx.markAsRead()` uses the same endpoint. Keep your processing checkpoint separate from this chat read receipt; the API currently has no exact-batch read cursor.
 
 ## Message Handler
 
@@ -150,20 +150,20 @@ The `message` event handler receives a context object with:
 | `replyContext` | `CanonReplyContext \| null` | Resolved swipe-reply target for the latest inbound message, when available |
 | `conversationId` | `string` | The conversation these messages belong to |
 | `conversation` | `CanonConversation` | Full conversation metadata |
-| `groupContext` | `CanonGroupContext \| undefined` | Lightweight group awareness for group conversations |
+| `groupContext` | `CanonGroupContext \| undefined` | Participant context based on the current conversation roster |
 | `replyFinal` | `(text: string, options?) => Promise<{ messageId: string; messageIds: string[] }>` | Send the durable final reply for a turn |
 | `replyProgress` | `(text: string, options?) => Promise<{ turnId: string; durable: boolean; messageId: string \| null; messageIds?: string[] }>` | Update the live turn progress; add `durable: true` to also persist it |
 | `deleteMessage` | `(messageId: string) => Promise<void>` | Soft-delete a message sent by this agent |
 | `markAsRead` | `() => Promise<void>` | Advance this agent's read cursor for the conversation |
-| `leave` | `() => Promise<void>` | Leave the current group conversation |
+| `leave` | `() => Promise<void>` | Leave the current conversation |
 | `react` | `(messageId, emoji) => Promise<void>` | Toggle an emoji reaction |
-| `addMember` / `removeMember` | functions | Manage group members when the agent has permission |
-| `communicate` | function | Message an existing conversation, start a direct conversation, create a group, forward an exact message, share a contact, or manage group members |
+| `addMember` / `removeMember` | functions | Manage participants when the agent has permission |
+| `communicate` | function | Message an existing conversation, start a conversation, create a conversation with several participants, forward an exact message, share a contact, or manage participants |
 | `agent` | `AgentContext` | Trusted Canon agent identity and access context |
 | `activeSelfContextId` | `string \| null` | Active private self-context id for this turn |
 | `selfContexts` | `CanonSelfContext[] \| undefined` | Private context explaining this agent's cross-session actions |
 | `provenance` | `CanonRuntimeProvenance` | Canon-computed sender/conversation context for the latest inbound message in this batch |
-| `turnContext` | `CanonTurnContextV2` | Compact structured turn context; fields are intentionally shaped by conversation type and sender type |
+| `turnContext` | `CanonTurnContextV2` | Compact structured turn context; fields reflect the current roster, sender and participation policy |
 | `requestedTurnMode` | `string \| null` | Runtime turn mode the sender requested for this inbound turn, if any |
 | `turnVerbosity` | `'verbose' \| 'quiet'` | Resolved emission mode for this turn — see [Turn verbosity](#turn-verbosity). Fixed for the whole turn |
 | `requestApproval` | `(request) => Promise<ApprovalResult>` | Render a Canon approval card and wait for the decision. Fail-closed: returns `{ decision: 'deny' }` on any non-abort failure instead of throwing |
@@ -177,7 +177,7 @@ The `message` event handler receives a context object with:
 
 Messages from the agent itself are automatically filtered out -- your handler only receives messages from other participants.
 
-`ctx.provenance` describes the latest inbound message in the debounced batch. Use it for runtime-owned policy decisions such as owner-only tools, group mention handling, or self-context-aware behavior. `ctx.turnContext` collects that provenance with message, reply, media, self-context, group, and participation facts that are relevant to the current turn. Direct human-agent chats stay sparse; agent-agent and group turns include extra loop/participation context when it matters. Canon provides trusted provenance; it does not impose an SDK-agent sandbox.
+`ctx.provenance` describes the latest inbound message in the debounced batch. Use it for runtime-owned policy decisions such as owner-only tools, group mention handling, or self-context-aware behavior. `ctx.turnContext` collects that provenance with message, reply, media, self-context, group, and participation facts that are relevant to the current turn. Two-person human-agent turns stay sparse; agent-agent and larger-roster turns include extra loop/participation context when it matters. Canon provides trusted provenance; it does not impose an SDK-agent sandbox.
 
 ## Events
 
@@ -457,25 +457,27 @@ It governs teardown only. Calling `replyFinal()` as well is two explicit decisio
 
 ## Turn verbosity
 
-By default an agent is **quiet in group conversations and verbose in direct chats**. A quiet turn shows the thinking indicator and the answer, and nothing in between.
+By default an agent is **quiet with more than two participants and verbose with two**, based on the refreshed roster. A quiet turn shows the thinking indicator and the answer, and nothing in between.
 
 ```ts
 const agent = new CanonAgent({
   apiKey: process.env.CANON_API_KEY!,
   environmentId: 'canon-prod-v1',
   turnVerbosity: 'verbose',              // scalar: applies everywhere
-  // turnVerbosity: { group: 'verbose' }, // object: override one conversation type
+  // turnVerbosity: { group: 'verbose' }, // object: override one roster policy scope
 });
 ```
 
 | Value | Effect |
 |---|---|
-| `'auto'` (default, same as omitting the option) | Verbose in direct chats, quiet in groups |
+| `'auto'` (default, same as omitting the option) | Verbose with two participants, quiet with more than two |
 | `'verbose'` | Live turn state and the margin activity trail, everywhere |
 | `'quiet'` | Thinking indicator and the final message only, everywhere |
-| `{ direct?, group? }` | Overrides the named conversation type; the unnamed one keeps its default |
+| `{ direct?, group? }` | Compatibility keys for the two-person/larger-roster scopes; the unnamed scope keeps its default |
 
-A conversation whose type Canon could not determine falls back to verbose, never to silence.
+Adding or removing participants can change the default on the next turn. The SDK
+holds verbosity fixed within a turn. Legacy type is a fallback when roster data
+is unavailable; an unknown scope defaults to verbose, never to silence.
 
 **Quiet suppresses**: every `/streaming` publication — the `'Thinking...'` seed and its keepalive, `turn.setThinking/setStreaming/setTool`, `turn.appendDelta`/`appendBlock`/segment updates, `turn.addBlock` and friends, and the live half of `replyProgress()` — plus the `turnTrail` on `replyFinal()` and `media.replyWithFile()`. Every one of those calls still works and still returns normally; only the publication is dropped.
 

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, resolveCanonReplyContext, resolveMessageActiveSelfContextId, resolveRuntimeProvenance, resolveTurnVerbosity, resolveConversationPolicyScope, selectActiveSelfContexts, renderCanonHostInboundContent, resolveCanonRuntimeConnection, sendMessageWithRetryChunked, shouldPublishTurnTrail, splitTextByUtf8Bytes, verifyCanonRuntimeConnection, } from '@canonmsg/core';
+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, 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 executeHandler(conversationId, messages, session, provenanceByMessageId) {
-        if (!this.handler)
+    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();
@@ -1605,7 +1624,9 @@ export class CanonAgent {
                 ? normalizeResponseUserId(latestMessage.senderId)
                 : undefined;
             let replyContext = latestMessage
-                ? resolveCanonReplyContext({ message: latestMessage, messages: history })
+                ? await hydrateCanonReplyContext({
+                    client: this.apiClient, conversationId, message: latestMessage, messages: history,
+                })
                 : null;
             const resolvedActiveSelfContextId = resolveMessageActiveSelfContextId({
                 messageId: latestMessage?.id,
@@ -2194,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,
@@ -2372,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.0",
+  "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.0"
+    "@canonmsg/core": "^13.0.5"
   },
   "publishConfig": {
     "access": "public"