@canonmsg/agent-sdk 10.4.0 → 11.0.1

package/README.md

@@ -34,9 +34,15 @@ await agent.start();
 npm install @canonmsg/agent-sdk
 ```
 
-The only runtime dependency is `@canonmsg/core`, which npm installs for you. Everything else is native `fetch` and `ReadableStream` (Node.js 18+).
+The SDK uses `@canonmsg/core` and the shared `@canonmsg/endpoint` engine. Node.js 22.22.3 or later is required.
 
-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.
+The endpoint owns stable installation and operation IDs, SQLite outbox/inbox state, live transport, receipt recovery, conversation synchronization, and upload dependencies. `CanonAgent` adds handler and native-session behavior. Set `CANON_ENDPOINT_STATE_DIR` to a persistent private directory; the default is `~/.canon/endpoint`. Keep this directory when upgrading or restarting a runtime.
+
+Replicated or ephemeral cloud deployments must inject an operator-owned endpoint store through `endpoint: { endpoint: sharedEndpoint }`. File delivery also needs a durable `mediaBytes` adapter or persistent `mediaDirectory`; a temporary container filesystem is not a delivery journal. All replicas for one installation share the same store namespace. A process must not replay an uncertain provider call automatically.
+
+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 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
 
@@ -46,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) |
@@ -123,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
 
@@ -144,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 |
@@ -171,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
 
@@ -451,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

@@ -26,7 +26,7 @@ export function createCanonAttachedSession(options) {
         rtdbUrl: connection.rtdbUrl,
         firebaseWebApiKey: connection.firebaseApiKey,
     });
-    const client = options.transport?.client ?? new CanonClient(connection.apiKey, runtimeConnection.apiBaseUrl);
+    const client = options.transport?.client ?? new CanonClient(connection.apiKey, runtimeConnection.apiBaseUrl, { environmentId: runtimeConnection.environmentId, streamUrl: runtimeConnection.streamUrl });
     let stopped = false;
     let running = false;
     let connected = false;
@@ -36,6 +36,8 @@ export function createCanonAttachedSession(options) {
     let coreStopPromise;
     let timer;
     let stream;
+    let endpoint;
+    let inbound;
     let unsubscribeStream;
     let publisher;
     let heartbeat;
@@ -82,6 +84,7 @@ 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}`),
         isPublicationReady: () => options.transport?.isRouteActive?.(binding.conversationId) !== false,
         publisher: {
             prepare(input) {
@@ -181,10 +184,9 @@ export function createCanonAttachedSession(options) {
         void stop().catch((error) => report(error, 'detach'));
     }
     async function verifyMembership() {
-        const conversations = await client.getConversations();
+        const conversation = await client.getConversation(binding.conversationId);
         if (stopped)
             return false;
-        const conversation = conversations.find((entry) => entry.id === binding.conversationId);
         currentConversation = conversation ?? null;
         if (!conversation?.memberIds.includes(binding.agentId)) {
             detach('conversation-membership-lost');
@@ -236,6 +238,15 @@ export function createCanonAttachedSession(options) {
                 text: [...rosterLines, `Canon message from ${message.senderName ?? message.senderId} (${message.senderType}):\n\n${message.text}`].join('\n\n'),
                 ...(payload.replyAuthority ? { replyAuthority: payload.replyAuthority } : {}),
             });
+            // 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 (stopped)
                 return;
             reportedHistory.delete(message.id);
@@ -375,8 +386,8 @@ export function createCanonAttachedSession(options) {
             }
             if (stopped)
                 return;
-            const conversations = await client.getConversations();
-            const conversation = conversations.find((entry) => entry.id === binding.conversationId);
+            endpoint = await client.getEndpoint();
+            const conversation = await client.getConversation(binding.conversationId);
             if (!conversation || !conversation.memberIds.includes(binding.agentId)) {
                 throw new Error('The agent is not a member of the specified Canon conversation');
             }
@@ -417,8 +428,31 @@ 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');
+                        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');
+                    }
+                }, onError: (error) => report(error, 'inbound-recovery') });
+            inbound.start();
             const handler = {
-                onMessage: (payload) => track(receive(payload), 'receive'),
+                onMessage: (payload) => {
+                    if (payload.conversationId !== binding.conversationId)
+                        return;
+                    track(inbound.receive({ id: `message:${payload.conversationId}:${payload.message.id}`, kind: 'message.created',
+                        conversationId: payload.conversationId, durable: true, data: payload }), 'receive');
+                },
                 onAgentContext: (context) => {
                     currentOwnerId = context.ownerId;
                     if (context.agentId !== binding.agentId) {
@@ -429,8 +463,10 @@ export function createCanonAttachedSession(options) {
                 onConversationUpdated: (payload) => {
                     if (stopped || payload.conversationId !== binding.conversationId)
                         return;
-                    if (currentConversation)
+                    if (currentConversation) {
                         currentConversation = { ...currentConversation, ...payload.changes };
+                        track(client.rememberConversation(currentConversation), 'conversation-state');
+                    }
                     const members = payload.changes.memberIds;
                     if ((Array.isArray(members) && !members.includes(binding.agentId))
                         || payload.membershipChange?.removedMemberIds.includes(binding.agentId)
@@ -464,7 +500,7 @@ export function createCanonAttachedSession(options) {
                 unsubscribeStream = options.transport.subscribe(handler);
             else
                 stream = new CanonStream({
-                    apiKey: connection.apiKey, agentId: binding.agentId, streamUrl: runtimeConnection.streamUrl, handler,
+                    endpoint: await client.getEndpoint(), agentId: binding.agentId, handler,
                 });
             publishState(core.getState());
             // CanonStream.start runs for the lifetime of a fetch stream. Do not
@@ -498,6 +534,7 @@ export function createCanonAttachedSession(options) {
         stopCore();
         stopPromise = (async () => {
             await startPromise?.catch(() => { });
+            await inbound?.close();
             await cleanup();
             emit({ status: 'stopped' });
         })();

package/dist/canon-agent.js

@@ -1,4 +1,4 @@
-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, 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 { DEFAULT_RUNTIME_INPUT_TIMEOUT_MS, RUNTIME_INPUT_ID_PATTERN, buildRuntimeCardCreateArgs, normalizeResponseUserId, resolveRuntimeCardRouting, } from './runtime-card.js';
@@ -346,6 +346,7 @@ export class CanonAgent {
             historyLimit: 50,
             autoMarkRead: true,
             runtimeControlSurface: 'agent',
+            endpoint: {},
             ...options,
             environmentId: this.runtimeConnection.environmentId,
             baseUrl: this.runtimeConnection.apiBaseUrl,
@@ -353,7 +354,9 @@ export class CanonAgent {
             rtdbUrl: this.runtimeConnection.rtdbUrl,
             firebaseApiKey: this.runtimeConnection.firebaseWebApiKey,
         };
-        this.apiClient = new CanonClient(this.options.apiKey, this.options.baseUrl);
+        this.apiClient = new CanonClient(this.options.apiKey, this.options.baseUrl, {
+            environmentId: this.runtimeConnection.environmentId, streamUrl: this.runtimeConnection.streamUrl, ...options.endpoint,
+        });
         this.typingSignals = createTypingStatusPublisher({
             setTyping: (conversationId, typing, status) => status
                 ? this.apiClient.setTyping(conversationId, typing, status)
@@ -682,7 +685,7 @@ export class CanonAgent {
         if (generation !== this.lifecycleGeneration)
             return;
         this.voiceEventsEnabled = Boolean(this.callStartedHandler || this.callEndedHandler);
-        const rtm = new RealtimeManager(this.options.apiKey, this.debouncer, agentId, this.options.streamUrl, { enableVoiceEvents: this.voiceEventsEnabled });
+        const rtm = new RealtimeManager(this.options.apiKey, this.debouncer, agentId, this.options.streamUrl, { enableVoiceEvents: this.voiceEventsEnabled, endpoint: await this.apiClient.getEndpoint() });
         if (this.voiceEventsEnabled) {
             rtm.setCallHandlers({
                 onCallStarted: (payload) => {
@@ -1253,12 +1256,26 @@ export class CanonAgent {
     }
     async handleMessages(conversationId, messages, provenanceByMessageId) {
         const actionableMessages = this.filterApprovalReplyMessages(conversationId, messages);
-        if (actionableMessages.length === 0) {
-            return;
+        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');
+            }
         }
+        if (actionableMessages.length === 0)
+            return;
         messages = actionableMessages;
         if (!this.handler) {
-            console.warn(`[canon-sdk] No message handler registered — messages for ${conversationId} dropped. Call agent.on('message', handler) before starting.`);
+            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');
+            }
+            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);
@@ -1280,50 +1297,40 @@ export class CanonAgent {
         // 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.
-        let membersBeforeRefresh = this.conversationMemberIds.get(conversationId);
-        let conversations;
-        try {
-            conversations = await this.apiClient.getConversations();
-        }
-        catch {
-            // Realtime delivery has already deduplicated these IDs. Retry this read
-            // here once; throwing does not arrange replay or requeue the input.
-            await sleep(100);
-            membersBeforeRefresh = this.conversationMemberIds.get(conversationId);
-            try {
-                conversations = await this.apiClient.getConversations();
-            }
-            catch (error) {
-                console.error(`[canon-sdk] Pre-turn conversation refresh failed for ${conversationId}:`, error);
-                return;
+        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);
             }
+        };
+        let conversation;
+        try {
+            conversation = await this.apiClient.getConversation(conversationId);
         }
-        let conversation = conversations.find((c) => c.id === conversationId);
-        if (!conversation)
+        catch (error) {
+            await setInputState('deferred', 'membership-unavailable');
+            console.error(`[canon-sdk] Input deferred until conversation refresh recovers for ${conversationId}:`, error);
             return;
-        const membersDuringRefresh = this.conversationMemberIds.get(conversationId);
-        const currentRevision = this.conversationMembershipRevisions.get(conversationId);
-        const refreshedRevision = knownMembershipRevision(conversation.membershipRevision);
-        const comparableRevisions = currentRevision !== undefined && refreshedRevision !== undefined;
-        const keepCachedRoster = comparableRevisions
-            ? currentRevision > refreshedRevision
-            : membersDuringRefresh !== membersBeforeRefresh;
-        if (membersDuringRefresh && keepCachedRoster) {
-            // Prefer the higher known revision. For legacy unversioned snapshots,
-            // retain an event received while the request was pending.
-            conversation = { ...conversation, memberIds: membersDuringRefresh, membershipRevision: currentRevision };
         }
-        else {
-            this.rememberConversationMembers([conversation]);
+        if (!conversation) {
+            await setInputState('settled', 'conversation-unavailable');
+            return;
         }
+        this.rememberConversationMembers([conversation]);
         const currentMembers = this.conversationMemberIds.get(conversationId);
-        if (currentMembers && this.agentId && !currentMembers.includes(this.agentId))
+        if (currentMembers && this.agentId && !currentMembers.includes(this.agentId)) {
+            await setInputState('settled', '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))
+        if (acceptedMembers && this.agentId && !acceptedMembers.includes(this.agentId)) {
+            await setInputState('settled', 'membership-lost');
             return;
+        }
         const turnId = randomUUID();
         const turnOpenedAt = Date.now();
         let turnState = 'thinking';
@@ -1477,7 +1484,7 @@ export class CanonAgent {
                 this.sessionManager.seedHistory(conversationId, history);
             }
             // Build reply functions
-            const replyFinal = async (text, options) => {
+            const replyFinal = async (text, options, delivery) => {
                 throwIfAborted();
                 try {
                     await this.typingSignals.start(conversationId, 'typing');
@@ -1501,11 +1508,11 @@ export class CanonAgent {
                 };
                 let result;
                 try {
-                    result = await sendDurableMessage(text, finalOptions, ['sdk', 'final', conversationId, turnId]);
+                    result = await sendDurableMessage(text, finalOptions, ['sdk', 'final', conversationId, turnId], delivery);
                 }
                 catch (error) {
                     const chunked = isChunkedSendMessageError(error) ? error : null;
-                    if (!chunked || chunked.deliveredMessageIds.length === 0 || isAbortLikeError(error)) {
+                    if (!chunked || chunked.deliveredMessageIds.length === 0 || sendOptions.messageId || isAbortLikeError(error) || isPendingCanonOperation(error)) {
                         throw error;
                     }
                     const requestedReplyBehavior = sendOptions.metadata?.replyBehavior;
@@ -1598,7 +1605,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,
@@ -1623,9 +1632,11 @@ export class CanonAgent {
             // override below only covers a retry backoff.
             const abortAwareClient = Object.create(this.apiClient, {
                 sendMessage: {
-                    value: (targetConversationId, targetText, targetOptions) => {
+                    value: (targetConversationId, targetText, targetOptions, delivery) => {
                         throwIfAborted();
-                        return this.apiClient.sendMessage(targetConversationId, targetText, targetOptions);
+                        return delivery?.operationId
+                            ? this.apiClient.sendMessage(targetConversationId, targetText, targetOptions, delivery)
+                            : this.apiClient.sendMessage(targetConversationId, targetText, targetOptions);
                     },
                 },
             });
@@ -1637,7 +1648,7 @@ export class CanonAgent {
             // that FITS still goes out as a single message under the plain id with
             // untouched metadata, so the common case (and the interim→final handoff
             // that keys on that id) is unchanged.
-            const sendDurableMessage = async (text, options, fallbackMessageIdParts) => {
+            const sendDurableMessage = async (text, options, fallbackMessageIdParts, delivery) => {
                 // Counts every durable send the turn attempts, not just the ones that
                 // needed a generated id: teardown reads `durableMessageSequence` to
                 // decide whether the turn genuinely ended silent, and a reply sent
@@ -1649,7 +1660,9 @@ export class CanonAgent {
                     ...(options ?? {}),
                     messageId,
                 }, {
-                    sleep: (ms) => sleepWithAbort(ms, abortController.signal),
+                    signal: abortController.signal,
+                    ...(delivery?.operationId ? { operationId: delivery.operationId } : {}),
+                    ...(delivery?.replacesOperationId ? { replacesOperationId: delivery.replacesOperationId } : {}),
                 }, {
                     resumable: true,
                 });
@@ -1659,16 +1672,9 @@ export class CanonAgent {
                 // the end of the answer, not its head. `messageIds` has the full set.
                 return { messageId: messageIds[messageIds.length - 1], messageIds };
             };
-            // Build agent context (fallback to minimal if not yet received)
-            const agent = this.agentContext ?? {
-                agentId: this.agentId,
-                ownerId: '',
-                ownerName: '',
-                discoverable: false,
-                inboundPolicy: 'approval-required',
-                outboundPolicy: 'approval-required',
-                groupJoinPolicy: 'approval-required',
-            };
+            // Runtime context must come from authenticated agent metadata. A synthetic
+            // generation cannot authorize an endpoint or a new owner's native work.
+            const agent = this.agentContext ?? await this.apiClient.getAgentMe();
             const provenance = latestMessage
                 ? resolveRuntimeProvenance({
                     provenance: provenanceByMessageId?.get(latestMessage.id) ?? null,
@@ -2187,8 +2193,15 @@ export class CanonAgent {
                     catch { }
                 }
             };
-            // Invoke handler
+            // 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({
                 messages: hydratedMessages,
                 history,
@@ -2197,6 +2210,19 @@ export class CanonAgent {
                 conversation,
                 ...(groupContext ? { groupContext } : {}),
                 replyFinal,
+                getReplyOperation: (messageId, delivery) => this.apiClient.getMessageOperation(conversationId, messageId, delivery),
+                waitForReply: async (operationId) => {
+                    throwIfAborted();
+                    durableMessageSequence += 1;
+                    const result = await this.apiClient.waitForOperation(operationId, { signal: abortController.signal });
+                    if (typeof result?.messageId !== 'string' || !result.messageId)
+                        throw new Error('Canon returned a malformed message receipt');
+                    try {
+                        await this.typingSignals.clear(conversationId);
+                    }
+                    catch { }
+                    return { messageId: result.messageId, messageIds: result.messageIds ?? [result.messageId] };
+                },
                 replyProgress,
                 deleteMessage,
                 markAsRead,
@@ -2349,6 +2375,7 @@ export class CanonAgent {
                     },
                 },
             });
+            await setInputState('settled', 'handler-completed');
             // Auto-mark conversation as read after successful processing
             if (this.options.autoMarkRead) {
                 try {

package/dist/media.d.ts

@@ -15,6 +15,8 @@ export interface MaterializeMediaOptions {
     onError?: (error: unknown, attachment: MediaAttachment, index: number) => void;
 }
 export interface UploadMediaFileOptions {
+    /** Stable native/product job key for upload recovery across restarts. */
+    attachmentId?: string;
     fileName?: string;
     mimeType?: string;
     durationMs?: number;

package/dist/media.js

@@ -1,4 +1,4 @@
-import { createReadStream, createWriteStream } from 'node:fs';
+import { createWriteStream } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import { mkdir, open, rename, stat, unlink } from 'node:fs/promises';
 import { basename, dirname, extname, join } from 'node:path';
@@ -321,98 +321,47 @@ export async function uploadMediaFile(client, conversationId, filePath, options)
     }
     const mimeType = inferUploadMimeType(filePath, options?.mimeType);
     const fileName = options?.fileName ?? basename(filePath);
-    const session = await client.createResumableMediaUpload(conversationId, fileStat.size, mimeType, fileName);
-    options?.signal?.throwIfAborted();
-    if (typeof session.uploadId !== 'string' || session.uploadId.length === 0) {
-        throw new Error('Canon returned an invalid resumable upload ID');
-    }
-    if (session.sizeBytes !== fileStat.size) {
-        throw new Error('Canon resumable upload size does not match the local file');
-    }
-    if (typeof session.mimeType !== 'string' || session.mimeType.length === 0) {
-        throw new Error('Canon returned an invalid resumable upload MIME type');
-    }
-    let uploadUrl;
-    try {
-        uploadUrl = new URL(session.uploadUrl);
-    }
-    catch {
-        throw new Error('Canon returned an invalid resumable upload URL');
-    }
-    if (uploadUrl.protocol !== 'https:') {
-        throw new Error('Canon returned a non-HTTPS resumable upload URL');
-    }
-    if (uploadUrl.hostname !== 'storage.googleapis.com'
-        || uploadUrl.username.length > 0
-        || uploadUrl.password.length > 0) {
-        throw new Error('Canon returned an untrusted resumable upload URL');
-    }
-    const fetchImpl = ensureFetch(options?.fetchImpl);
-    const uploadResponse = await fetchImpl(uploadUrl, {
-        method: 'PUT',
-        headers: {
-            'Content-Type': session.mimeType,
-            'Content-Length': String(fileStat.size),
-            'Content-Range': `bytes 0-${fileStat.size - 1}/${fileStat.size}`,
-        },
-        body: createReadStream(filePath),
-        signal: options?.signal,
-        // Node requires this for streaming request bodies. It is intentionally
-        // outside the DOM RequestInit type but supported by the built-in fetch.
-        duplex: 'half',
-    });
-    if (!uploadResponse.ok) {
-        throw new Error(`Failed to upload Canon media (${uploadResponse.status} ${uploadResponse.statusText})`);
-    }
-    options?.signal?.throwIfAborted();
-    const finalized = await client.finalizeResumableMediaUpload(session.uploadId);
-    options?.signal?.throwIfAborted();
-    if (finalized.uploadId !== session.uploadId) {
-        throw new Error('Canon resumable upload result does not match its session');
-    }
-    if (finalized.attachment.uploadId !== undefined
-        && finalized.attachment.uploadId !== session.uploadId) {
-        throw new Error('Canon resumable upload attachment does not match its session');
-    }
-    const uploaded = {
-        ...finalized,
-        attachment: {
-            ...finalized.attachment,
-            uploadId: session.uploadId,
-        },
-    };
-    if (uploaded.attachment.kind === 'audio'
-        && typeof options?.durationMs === 'number'
-        && Number.isFinite(options.durationMs)
-        && options.durationMs > 0) {
-        return {
-            ...uploaded,
-            attachment: {
-                ...uploaded.attachment,
-                durationMs: Math.round(options.durationMs),
-            },
-        };
-    }
-    return uploaded;
+    const media = await client.getFileMediaPipeline(options?.fetchImpl);
+    const [attachment] = await media.prepare({ conversationId, attachmentId: options?.attachmentId ?? randomUUID(),
+        files: [{ source: filePath, descriptor: { mimeType, sizeBytes: fileStat.size, fileName,
+                    ...(options?.durationMs !== undefined ? { durationMs: options.durationMs } : {}) } }],
+    }, { signal: options?.signal });
+    if (typeof attachment?.uploadId !== 'string' || typeof attachment.url !== 'string') {
+        throw new Error('Canon returned an invalid prepared attachment');
+    }
+    return { uploadId: attachment.uploadId, url: attachment.url, attachment: attachment };
 }
 export async function sendMediaFileMessage(client, conversationId, filePath, text = '', options) {
-    const { fileName, mimeType, durationMs, fetchImpl, signal, canPublish, ...sendOptions } = options ?? {};
-    const uploaded = await uploadMediaFile(client, conversationId, filePath, {
-        ...(fileName ? { fileName } : {}),
-        ...(mimeType ? { mimeType } : {}),
-        ...(durationMs != null ? { durationMs } : {}),
-        ...(fetchImpl ? { fetchImpl } : {}),
-        ...(signal ? { signal } : {}),
-    });
+    const { fileName, mimeType, durationMs, fetchImpl, signal, canPublish, attachmentId: _attachmentId, ...sendOptions } = options ?? {};
     signal?.throwIfAborted();
-    if (canPublish && !canPublish()) {
-        throw new Error('Canon media publication withheld by current routing policy');
-    }
-    return client.sendMessage(conversationId, text, {
-        ...sendOptions,
-        contentType: uploaded.attachment.kind,
-        attachments: [uploaded.attachment],
-    });
+    const info = await stat(filePath);
+    if (!info.isFile() || info.size <= 0 || info.size > MAX_CANON_MEDIA_BYTES) {
+        throw new Error('Canon media must be a regular file from 1 byte to 100 MiB');
+    }
+    const effectiveMimeType = inferUploadMimeType(filePath, mimeType);
+    const contentType = effectiveMimeType.startsWith('image/') ? 'image'
+        : effectiveMimeType.startsWith('video/') ? 'video'
+            : effectiveMimeType.startsWith('audio/') ? 'audio' : 'file';
+    // Automatic artifacts keep their audience across upload and every later
+    // receipt retry. A membership change may reduce, but never expand, that audience.
+    const initialRoom = canPublish ? await client.getConversation(conversationId) : null;
+    const originalMembers = new Set(initialRoom?.memberIds ?? []);
+    const beforePublish = canPublish ? async () => {
+        const current = await client.getConversation(conversationId);
+        return !!current && originalMembers.size > 0
+            && current.memberIds.every((id) => originalMembers.has(id)) && canPublish();
+    } : undefined;
+    const messageId = sendOptions.messageId ?? randomUUID();
+    const pipeline = await client.getFileMediaPipeline(fetchImpl);
+    const delivered = await pipeline.send({
+        conversationId, messageId,
+        message: { ...sendOptions, text, contentType },
+        files: [{ source: filePath, descriptor: {
+                    mimeType: effectiveMimeType, sizeBytes: info.size, fileName: fileName ?? basename(filePath),
+                    ...(durationMs != null ? { durationMs } : {}),
+                } }],
+    }, { ...(signal ? { signal } : {}), ...(beforePublish ? { beforePublish } : {}) });
+    return { messageId: delivered };
 }
 /**
  * Resolve the effective MIME type of a materialized attachment, falling back

package/dist/realtime.d.ts

@@ -1,4 +1,4 @@
-import { type AgentContext, type ContactAddedPayload, type ContactRemovedPayload, type ConversationUpdatedPayload, type MessageUpdatedPayload, type ParticipationSuppressedPayload, type VoiceSessionEventPayload } from '@canonmsg/core';
+import { type CanonEndpoint, type AgentContext, type ContactAddedPayload, type ContactRemovedPayload, type ConversationUpdatedPayload, type MessageUpdatedPayload, type ParticipationSuppressedPayload, type VoiceSessionEventPayload } from '@canonmsg/core';
 import { Debouncer } from './debouncer.js';
 /**
  * Wraps @canonmsg/core's CanonStream with SDK-specific features:
@@ -9,8 +9,8 @@ import { Debouncer } from './debouncer.js';
 export declare class RealtimeManager {
     private debouncer;
     private stream;
-    /** Recent inbound message IDs (`conversationId:messageId`) for cross-flush dedupe. */
-    private readonly recentInboundMessageIds;
+    private readonly endpoint;
+    private readonly inbound;
     private lastSseErrorKey;
     private lastSseErrorAt;
     private suppressedSseErrorCount;
@@ -25,12 +25,12 @@ export declare class RealtimeManager {
     private onDisconnected;
     private onCallStarted;
     private onCallEnded;
-    constructor(apiKey: string, debouncer: Debouncer, agentId: string, streamUrl?: string, options?: {
+    constructor(apiKey: string, debouncer: Debouncer, agentId: string, streamUrl: string | undefined, options: {
         enableVoiceEvents?: boolean;
+        endpoint: CanonEndpoint;
     });
-    private hasSeenInboundMessage;
-    private recordSeenInboundMessage;
-    private pruneRecentInboundMessageIds;
+    private receive;
+    private offer;
     private logSseError;
     setOnAgentContext(cb: (ctx: AgentContext) => void): void;
     setContactGraphHandlers(handlers: {

package/dist/realtime.js

@@ -1,6 +1,4 @@
 import { CanonStream, } from '@canonmsg/core';
-const RECENT_INBOUND_TTL_MS = 30 * 60 * 1000;
-const MAX_RECENT_INBOUND_MESSAGE_IDS = 5000;
 /**
  * Wraps @canonmsg/core's CanonStream with SDK-specific features:
  * - Debouncer integration (message batching)
@@ -10,8 +8,8 @@ const MAX_RECENT_INBOUND_MESSAGE_IDS = 5000;
 export class RealtimeManager {
     debouncer;
     stream;
-    /** Recent inbound message IDs (`conversationId:messageId`) for cross-flush dedupe. */
-    recentInboundMessageIds = new Map();
+    endpoint;
+    inbound;
     lastSseErrorKey = null;
     lastSseErrorAt = 0;
     suppressedSseErrorCount = 0;
@@ -28,10 +26,13 @@ export class RealtimeManager {
     onCallEnded = null;
     constructor(apiKey, debouncer, agentId, streamUrl, options) {
         this.debouncer = debouncer;
+        this.endpoint = options.endpoint;
+        this.inbound = this.endpoint.acceptInbound({ kind: 'message.created',
+            offer: (event) => this.offer(event.data),
+            onError: (error) => this.logSseError(error instanceof Error ? error : new Error(String(error))), });
         this.stream = new CanonStream({
-            apiKey,
+            endpoint: this.endpoint,
             agentId,
-            streamUrl,
             handler: {
                 // The voice family is requested from handler PRESENCE at stream
                 // construction, so these delegating closures exist only when the
@@ -49,44 +50,7 @@ export class RealtimeManager {
                     }
                     : {}),
                 onMessage: (payload) => {
-                    // Cross-flush id dedupe: SSE replay overlap must never double-fire
-                    // a turn for the same message.
-                    if (this.hasSeenInboundMessage(payload.conversationId, payload.message.id)) {
-                        return;
-                    }
-                    this.recordSeenInboundMessage(payload.conversationId, payload.message.id);
-                    if (payload.turnDispatch && payload.turnDispatch.kind !== 'run_turn') {
-                        console.error(`[canon-sdk] Ignoring server-dispatched observe-only message in ${payload.conversationId}: ${payload.turnDispatch.reason}`);
-                        return;
-                    }
-                    const m = payload.message;
-                    const message = {
-                        id: m.id,
-                        senderId: m.senderId,
-                        ...(m.senderName ? { senderName: m.senderName } : {}),
-                        senderType: m.senderType ?? 'human',
-                        isOwner: m.isOwner ?? false,
-                        contentType: m.contentType ?? 'text',
-                        text: m.text ?? null,
-                        attachments: m.attachments ?? [],
-                        mentions: m.mentions ?? [],
-                        ...(m.reactions ? { reactions: m.reactions } : {}),
-                        replyTo: m.replyTo ?? null,
-                        replyToPosition: m.replyToPosition ?? null,
-                        ...(m.forwarded === true || m.forwardedFrom
-                            ? { forwarded: true }
-                            : {}),
-                        ...(m.forwardedFrom
-                            ? { forwardedFrom: m.forwardedFrom }
-                            : {}),
-                        status: 'sent',
-                        deleted: false,
-                        createdAt: m.createdAt ?? new Date().toISOString(),
-                        ...(m.contactCard ? { contactCard: m.contactCard } : {}),
-                        ...(m.metadata ? { metadata: m.metadata } : {}),
-                        ...(payload.replyAuthority ? { replyAuthority: payload.replyAuthority } : {}),
-                    };
-                    this.debouncer.add(payload.conversationId, message, payload.provenance ?? null);
+                    void this.receive(payload).catch((error) => this.logSseError(error instanceof Error ? error : new Error(String(error))));
                 },
                 onMessageDeleted: (payload) => {
                     this.debouncer.removeMessage(payload.conversationId, payload.messageId);
@@ -105,7 +69,9 @@ export class RealtimeManager {
                     this.onContactRemoved?.(payload);
                 },
                 onConversationUpdated: (payload) => {
-                    this.onConversationUpdated?.(payload);
+                    void this.endpoint.applyConversationSnapshot({ id: payload.conversationId, ...payload.changes })
+                        .then(({ id: _id, ...changes }) => this.onConversationUpdated?.({ ...payload, changes }))
+                        .catch((error) => this.logSseError(error instanceof Error ? error : new Error(String(error))));
                 },
                 onParticipationSuppressed: (payload) => {
                     this.onParticipationSuppressed?.(payload);
@@ -117,7 +83,7 @@ export class RealtimeManager {
                     this.onDisconnected?.();
                 },
                 onReplayExpired: (payload) => {
-                    console.error(`[canon-sdk] SSE replay window expired${payload.lastAvailableId ? ` (oldest available event: ${payload.lastAvailableId})` : ''}; missed history is available via explicit REST fetch`);
+                    console.error(`[canon-sdk] SSE replay window expired${payload.lastAvailableId ? ` (oldest available event: ${payload.lastAvailableId})` : ''}; the endpoint is recovering the durable gap`);
                 },
                 onError: (err) => {
                     this.logSseError(err);
@@ -125,27 +91,45 @@ export class RealtimeManager {
             },
         });
     }
-    hasSeenInboundMessage(conversationId, messageId) {
-        return this.recentInboundMessageIds.has(`${conversationId}:${messageId}`);
-    }
-    recordSeenInboundMessage(conversationId, messageId) {
-        const now = Date.now();
-        this.recentInboundMessageIds.set(`${conversationId}:${messageId}`, now);
-        this.pruneRecentInboundMessageIds(now);
+    async receive(payload) {
+        await this.inbound.receive({ id: `message:${payload.conversationId}:${payload.message.id}`,
+            kind: 'message.created', conversationId: payload.conversationId, durable: true,
+            data: payload });
     }
-    pruneRecentInboundMessageIds(now = Date.now()) {
-        const cutoff = now - RECENT_INBOUND_TTL_MS;
-        for (const [key, seenAt] of this.recentInboundMessageIds) {
-            if (seenAt < cutoff) {
-                this.recentInboundMessageIds.delete(key);
-            }
-        }
-        while (this.recentInboundMessageIds.size > MAX_RECENT_INBOUND_MESSAGE_IDS) {
-            const oldestKey = this.recentInboundMessageIds.keys().next().value;
-            if (!oldestKey)
-                break;
-            this.recentInboundMessageIds.delete(oldestKey);
+    async offer(payload) {
+        const id = `message:${payload.conversationId}:${payload.message.id}`;
+        if (payload.turnDispatch && payload.turnDispatch.kind !== 'run_turn') {
+            await this.endpoint.setInboundState(id, 'settled', 'observe-only');
+            return;
         }
+        const m = payload.message;
+        const message = {
+            id: m.id,
+            senderId: m.senderId,
+            ...(m.senderName ? { senderName: m.senderName } : {}),
+            senderType: m.senderType ?? 'human',
+            isOwner: m.isOwner ?? false,
+            contentType: m.contentType ?? 'text',
+            text: m.text ?? null,
+            attachments: m.attachments ?? [],
+            mentions: m.mentions ?? [],
+            ...(m.reactions ? { reactions: m.reactions } : {}),
+            replyTo: m.replyTo ?? null,
+            replyToPosition: m.replyToPosition ?? null,
+            ...(m.forwarded === true || m.forwardedFrom
+                ? { forwarded: true }
+                : {}),
+            ...(m.forwardedFrom
+                ? { forwardedFrom: m.forwardedFrom }
+                : {}),
+            status: 'sent',
+            deleted: false,
+            createdAt: m.createdAt ?? new Date().toISOString(),
+            ...(m.contactCard ? { contactCard: m.contactCard } : {}),
+            ...(m.metadata ? { metadata: m.metadata } : {}),
+            ...(payload.replyAuthority ? { replyAuthority: payload.replyAuthority } : {}),
+        };
+        this.debouncer.add(payload.conversationId, message, payload.provenance ?? null);
     }
     logSseError(err) {
         const code = err.code;
@@ -196,9 +180,11 @@ export class RealtimeManager {
         this.onCallEnded = handlers.onCallEnded ?? null;
     }
     async start() {
+        this.inbound.start();
         await this.stream.start();
     }
     stop() {
+        void this.inbound.close();
         this.stream.stop();
     }
 }

package/dist/types.d.ts

@@ -166,7 +166,16 @@ export interface MessageHandlerContext {
     conversation: CanonConversation;
     /** Lightweight group awareness, present for group conversations. */
     groupContext?: CanonGroupContext;
-    replyFinal: (text: string, options?: SendMessageOptions) => Promise<FinalMessageResult>;
+    replyFinal: (text: string, options?: SendMessageOptions, delivery?: {
+        operationId?: string;
+        replacesOperationId?: string;
+    }) => Promise<FinalMessageResult>;
+    /** Inspect a prior reply before renewing media or recording product completion. */
+    getReplyOperation: (messageId: string, delivery?: {
+        operationId?: string;
+    }) => Promise<import('@canonmsg/core').CanonMessageOperation | undefined>;
+    /** Reconcile every part of a journaled reply without rebuilding its content. */
+    waitForReply: (operationId: string) => Promise<FinalMessageResult>;
     replyProgress: (text: string, options?: ProgressMessageOptions) => Promise<ProgressMessageResult>;
     /** Soft-delete a message (agent must be the sender) */
     deleteMessage: (messageId: string) => Promise<void>;
@@ -307,6 +316,8 @@ export interface CanonAgentConnectionOptions {
     firebaseApiKey?: string;
 }
 export interface CanonAgentOptions extends CanonAgentConnectionOptions {
+    /** Shared durable engine or persistent installation profile for this runtime. */
+    endpoint?: import('@canonmsg/core').CanonClientEndpointOptions;
     apiKey: string;
     /** `auto` resolves to SSE. */
     deliveryMode?: DeliveryMode;

package/dist/work-session-host.js

@@ -9,7 +9,7 @@ export function createCanonWorkSessionHost(options) {
     const runtime = resolveCanonRuntimeConnection({ environmentId: connection.environmentId,
         apiBaseUrl: connection.baseUrl, streamUrl: connection.streamUrl,
         rtdbUrl: connection.rtdbUrl, firebaseWebApiKey: connection.firebaseApiKey });
-    const client = new CanonClient(connection.apiKey, runtime.apiBaseUrl);
+    const client = new CanonClient(connection.apiKey, runtime.apiBaseUrl, { environmentId: runtime.environmentId, streamUrl: runtime.streamUrl });
     const journal = createWorkSessionJournal(options.store, {
         environmentId: connection.environmentId, agentId: connection.agentId, hostId: options.hostId,
     });
@@ -30,6 +30,7 @@ export function createCanonWorkSessionHost(options) {
     let transport;
     let stream;
     let connected = false;
+    let agentContext;
     let stopped = false;
     let startPromise;
     let stopPromise;
@@ -134,7 +135,7 @@ export function createCanonWorkSessionHost(options) {
             throw new Error('This conversation already has a work session.');
         if ([...rooms.values()].some((room) => room.binding.nativeSessionId === binding.nativeSessionId))
             throw new Error('This native session already has a different Canon audience.');
-        const conversation = (await client.getConversations()).find((entry) => entry.id === binding.conversationId);
+        const conversation = await client.getConversation(binding.conversationId);
         if (!conversation?.memberIds.includes(connection.agentId) || !conversation.memberIds.includes(broker.ownerId))
             throw new Error('The owner and agent must both be members of this conversation.');
         fence();
@@ -446,11 +447,19 @@ export function createCanonWorkSessionHost(options) {
             transport = { agentId: connection.agentId, environmentId: connection.environmentId, client, publisher,
                 hasPendingInteraction: (id) => pending.has(id),
                 isRouteActive: (id) => !stopped && rooms.get(id)?.acknowledged === true,
-                subscribe: (handler) => { handlers.add(handler); if (connected && !stopped)
-                    handler.onConnected?.(); return () => { handlers.delete(handler); }; } };
+                subscribe: (handler) => {
+                    handlers.add(handler);
+                    // Context is account state, not a one-shot notification. An attachment
+                    // created after stream startup needs the same trusted owner identity.
+                    if (!stopped && agentContext)
+                        handler.onAgentContext?.(agentContext);
+                    if (connected && !stopped)
+                        handler.onConnected?.();
+                    return () => { handlers.delete(handler); };
+                } };
             const connectionReady = new Promise((resolve, reject) => { resolveConnection = resolve; rejectConnection = reject; });
             const connectionTimer = setTimeout(() => rejectConnection?.(new Error('Canon stream did not connect; work-session setup was not started.')), connectTimeoutMs);
-            stream = new CanonStream({ apiKey: connection.apiKey, agentId: connection.agentId, streamUrl: runtime.streamUrl, handler: {
+            stream = new CanonStream({ endpoint: await client.getEndpoint(), agentId: connection.agentId, handler: {
                     onMessage: (payload) => {
                         if (stopped || !connected)
                             return;
@@ -462,6 +471,7 @@ export function createCanonWorkSessionHost(options) {
                             fail(new Error('Canon stream identity changed.'), 'stream-identity');
                             return;
                         }
+                        agentContext = context;
                         fanout('onAgentContext', context);
                     },
                     onConversationUpdated: (payload) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-sdk",
-  "version": "10.4.0",
+  "version": "11.0.1",
   "description": "Canon Agent SDK — build AI agents that participate in Canon conversations",
   "type": "module",
   "main": "dist/index.js",
@@ -25,10 +25,10 @@
     "prepack": "npm run build"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.22.3"
   },
   "dependencies": {
-    "@canonmsg/core": "^12.5.0"
+    "@canonmsg/core": "^13.0.4"
   },
   "publishConfig": {
     "access": "public"