@canonmsg/agent-sdk 10.4.0 → 11.0.0

package/README.md

@@ -34,7 +34,13 @@ 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.
+
+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 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.
 

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, resolveCanonReplyContext, 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;
@@ -1623,9 +1630,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 +1646,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 +1658,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 +1670,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 +2191,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 +2208,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 +2373,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.0",
   "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.0"
   },
   "publishConfig": {
     "access": "public"