@canonmsg/agent-sdk 3.1.0 → 3.2.2

package/dist/canon-agent.d.ts

@@ -1,4 +1,4 @@
-import { type AddMemberResult, type CanonContact, type CanonRuntimeActivityItem, type CanonRuntimeCommandDescriptor, type CanonRuntimeFact, type CanonRuntimePrimitiveId, type ContactCardPayload, type ClearRuntimeActivityOptions, type CreateContactRequestResult } from '@canonmsg/core';
+import { type AddMemberResult, type CanonContact, type CanonConversation, type CreateConversationResult, type CanonRuntimeActivityItem, type CanonRuntimeCommandDescriptor, type CanonRuntimeFact, type CanonRuntimePrimitiveId, type ContactCardPayload, type ClearRuntimeActivityOptions, type CreateContactRequestResult } from '@canonmsg/core';
 import type { CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, CreateConversationOptions, MessageHandler, MessageUpdatedHandler, ReachOutOptions, ReachOutResult, ContactRequestHandler, RuntimeSignalHandler, RuntimePrimitiveHandler } from './types.js';
 /**
  * Contact-graph operations exposed under `agent.contacts`. Wraps the REST
@@ -18,6 +18,11 @@ export interface AgentUsersAPI {
     block(userId: string): Promise<void>;
     unblock(userId: string): Promise<void>;
 }
+export interface AgentConversationsAPI {
+    list(options?: {
+        targetUserId?: string;
+    }): Promise<CanonConversation[]>;
+}
 export declare class CanonAgent {
     private options;
     private apiClient;
@@ -40,6 +45,8 @@ export declare class CanonAgent {
     readonly contacts: AgentContactsAPI;
     /** Block/unblock operations (`agent.users.*`). Initialized in the constructor. */
     readonly users: AgentUsersAPI;
+    /** Conversation discovery for choosing existing sessions intentionally. */
+    readonly conversations: AgentConversationsAPI;
     private readonly reachOutInFlight;
     private agentId;
     private agentContext;
@@ -49,9 +56,8 @@ export declare class CanonAgent {
     private cachedConversationIds;
     private running;
     private runtimeHeartbeatTimer;
-    private runtimeControlPollTimer;
-    private readonly lastSeenSignal;
-    private readonly primitiveRequestDedupe;
+    private rtdbHandle;
+    private controlPoller;
     private readonly activeAbortControllers;
     private readonly activeTurns;
     private readonly conversationMemberIds;
@@ -85,9 +91,7 @@ export declare class CanonAgent {
     reachOut(card: ContactCardPayload, options?: ReachOutOptions): Promise<ReachOutResult>;
     private executeReachOut;
     start(): Promise<void>;
-    createConversation(options: CreateConversationOptions): Promise<{
-        conversationId: string;
-    }>;
+    createConversation(options: CreateConversationOptions): Promise<CreateConversationResult>;
     updateTopic(conversationId: string, topic: string): Promise<void>;
     leaveConversation(conversationId: string): Promise<void>;
     updateConversationName(conversationId: string, name: string): Promise<void>;
@@ -132,20 +136,33 @@ export declare class CanonAgent {
     private rememberConversationMembers;
     private handleConversationUpdated;
     private buildGroupContext;
+    /**
+     * Shared `/control` channel poller, configured to the agent-sdk host
+     * profile pinned by core's characterization tests: flat 2s single-flight
+     * cadence, parallel conversations, signal + primitive keys (no session),
+     * eager signal baseline, and TTL'd primitive dedupe released on successful
+     * consume. The poller talks only to the scoped RTDB handle captured in
+     * start() — never the module-global default client.
+     */
+    private ensureControlPoller;
     private baselineRuntimeControlSignals;
     private startRuntimeControlPolling;
     private stopRuntimeControlPolling;
-    private pollRuntimeControls;
-    private handleRuntimePrimitiveRequests;
-    private clearRuntimePrimitiveRequest;
-    private prunePrimitiveRequestDedupe;
-    private handleRuntimeSignal;
+    private handleRuntimePrimitiveEvent;
+    private handleRuntimeSignalEvent;
     private firstActiveTurn;
     private publishAcceptedRuntimeSignal;
     private abortActiveTurns;
     private resolveBatchDeliveryIntent;
     private markQueuedMessagesAccepted;
     private notifyMessageInterrupt;
+    /**
+     * Builds a runtime-state publisher bound to this agent's scoped RTDB
+     * handle (captured in start()). Threading the handle keeps every
+     * publish on this agent's own credentials — without it the publisher
+     * would fall back to core's deprecated module-global RTDB client,
+     * where the last-started agent's token wins in multi-agent processes.
+     */
     private createRuntimeStatePublisher;
     private requireRuntimeStatePublisher;
     private handleMessages;

package/dist/canon-agent.js

@@ -1,4 +1,4 @@
-import { ApprovalManager, CanonClient, buildCanonTurnContextV2, buildCanonGroupContext, buildParticipationHistorySnapshot, createTurnOutputController, createRuntimeStatePublisher, createTypingStatusPublisher, diffCanonMemberIds, FINAL_MESSAGE_HANDOFF_MS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildRuntimeCardOutcome, buildRuntimeInputOutcome, initRTDBAuth, rtdbRead, rtdbWrite, normalizeTurnMetadata, reachOutToCanonContact, resolveCanonReplyContext, resolveMessageActiveSelfContextId, resolveRuntimeProvenance, selectActiveSelfContexts, renderCanonHostInboundContent, } from '@canonmsg/core';
+import { ApprovalManager, CanonClient, ControlChannelPoller, buildCanonTurnContextV2, buildCanonGroupContext, buildParticipationHistorySnapshot, createTurnOutputController, createRuntimeStatePublisher, createTypingStatusPublisher, diffCanonMemberIds, FINAL_MESSAGE_HANDOFF_MS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildRuntimeCardOutcome, buildRuntimeInputOutcome, initRTDBAuth, normalizeTurnMetadata, reachOutToCanonContact, resolveCanonReplyContext, resolveMessageActiveSelfContextId, resolveRuntimeProvenance, selectActiveSelfContexts, renderCanonHostInboundContent, } from '@canonmsg/core';
 import { randomUUID } from 'node:crypto';
 import { AuthManager } from './auth.js';
 import { Debouncer } from './debouncer.js';
@@ -6,6 +6,7 @@ import { buildRuntimeCardCreateArgs } from './runtime-card.js';
 import { materializeMessageMedia, materializeReplyContextMedia, sendMediaFileMessage, uploadMediaFile, } from './media.js';
 import { SessionManager } from './session-manager.js';
 const AGENT_RUNTIME_HEARTBEAT_MS = 30_000;
+const RUNTIME_CONTROL_POLL_INTERVAL_MS = 2_000;
 const RUNTIME_PRIMITIVE_DEDUPE_TTL_MS = 5 * 60 * 1000;
 const RUNTIME_PRIMITIVE_DEDUPE_MAX = 1_000;
 const DEFAULT_RUNTIME_INPUT_TIMEOUT_MS = 5 * 60_000;
@@ -245,6 +246,8 @@ export class CanonAgent {
     contacts;
     /** Block/unblock operations (`agent.users.*`). Initialized in the constructor. */
     users;
+    /** Conversation discovery for choosing existing sessions intentionally. */
+    conversations;
     reachOutInFlight = new Map();
     agentId = null;
     agentContext = null;
@@ -254,9 +257,8 @@ export class CanonAgent {
     cachedConversationIds = [];
     running = false;
     runtimeHeartbeatTimer = null;
-    runtimeControlPollTimer = null;
-    lastSeenSignal = new Map();
-    primitiveRequestDedupe = new Map();
+    rtdbHandle = null;
+    controlPoller = null;
     activeAbortControllers = new Map();
     activeTurns = new Map();
     conversationMemberIds = new Map();
@@ -292,6 +294,14 @@ export class CanonAgent {
             block: (userId) => apiClient.blockUser(userId),
             unblock: (userId) => apiClient.unblockUser(userId),
         };
+        this.conversations = {
+            list: async (options = {}) => {
+                const conversations = await apiClient.getConversations();
+                if (!options.targetUserId)
+                    return conversations;
+                return conversations.filter((conversation) => conversation.memberIds.includes(options.targetUserId));
+            },
+        };
         if (options.sessions?.enabled) {
             this.sessionManager = new SessionManager({
                 contextLimit: options.sessions.contextLimit,
@@ -457,7 +467,7 @@ export class CanonAgent {
         const contextualKey = options?.selfContext
             ? `${options.sourceConversationId ?? ''}\u0000${options.selfContext.type}\u0000${options.selfContext.context}`
             : '';
-        const inFlightKey = `${targetUserId}\u0000${options?.text ?? ''}\u0000${options?.requestMessage ?? ''}\u0000${JSON.stringify(options?.sessionConfig ?? null)}\u0000${contextualKey}`;
+        const inFlightKey = `${targetUserId}\u0000${options?.text ?? ''}\u0000${options?.requestMessage ?? ''}\u0000${JSON.stringify(options?.sessionConfig ?? null)}\u0000${JSON.stringify(options?.sessionSelection ?? null)}\u0000${contextualKey}`;
         const inFlight = this.reachOutInFlight.get(inFlightKey);
         if (inFlight)
             return inFlight;
@@ -482,6 +492,7 @@ export class CanonAgent {
                 selfContext: options.selfContext,
                 requestMessage: options.requestMessage ?? null,
                 sessionConfig: options.sessionConfig ?? null,
+                sessionSelection: options.sessionSelection,
             });
             return result.status === 'messaged'
                 ? {
@@ -489,6 +500,9 @@ export class CanonAgent {
                     conversationId: result.conversationId,
                     messageId: result.messageId,
                     selfContextId: result.selfContextId,
+                    created: result.created,
+                    reused: result.reused,
+                    sessionSelection: result.sessionSelection,
                 }
                 : result;
         }
@@ -497,13 +511,18 @@ export class CanonAgent {
             text: options?.text ?? null,
             requestMessage: options?.requestMessage ?? null,
             sessionConfig: options?.sessionConfig ?? null,
+            sessionSelection: options?.sessionSelection,
         });
     }
     async start() {
         if (this.running)
             return;
         this.running = true;
-        initRTDBAuth(this.apiClient);
+        // The single scoped RTDB client for this agent. Every RTDB consumer in
+        // the SDK (control poller, runtime-state publishers) threads this handle;
+        // the SDK never reads through core's deprecated module-global default,
+        // so multiple CanonAgents in one process cannot clobber each other.
+        this.rtdbHandle = initRTDBAuth(this.apiClient);
         // 1. Authenticate
         const { agentId } = await this.authManager.authenticate();
         this.agentId = agentId;
@@ -832,143 +851,104 @@ export class CanonAgent {
             membershipChange: input.membershipChange,
         });
     }
+    /**
+     * Shared `/control` channel poller, configured to the agent-sdk host
+     * profile pinned by core's characterization tests: flat 2s single-flight
+     * cadence, parallel conversations, signal + primitive keys (no session),
+     * eager signal baseline, and TTL'd primitive dedupe released on successful
+     * consume. The poller talks only to the scoped RTDB handle captured in
+     * start() — never the module-global default client.
+     */
+    ensureControlPoller() {
+        if (this.controlPoller)
+            return this.controlPoller;
+        if (!this.rtdbHandle)
+            return null;
+        this.controlPoller = new ControlChannelPoller({
+            rtdb: this.rtdbHandle,
+            agentId: () => this.agentId,
+            conversationIds: () => this.cachedConversationIds,
+            cadence: { kind: 'fixed', intervalMs: RUNTIME_CONTROL_POLL_INTERVAL_MS },
+            pollOnStart: false,
+            conversationConcurrency: 'parallel',
+            handlers: {
+                signal: {
+                    handle: (event) => this.handleRuntimeSignalEvent(event),
+                    consumeOnError: true,
+                },
+                primitive: {
+                    handle: (event) => this.handleRuntimePrimitiveEvent(event),
+                    consumeOnError: true,
+                    ordering: 'sequential',
+                    dedupeTtlMs: RUNTIME_PRIMITIVE_DEDUPE_TTL_MS,
+                    dedupeMaxEntries: RUNTIME_PRIMITIVE_DEDUPE_MAX,
+                    releaseDedupeOnConsume: true,
+                },
+            },
+            onError: (error) => {
+                // Read/consume failures stay silent (the legacy loop swallowed them);
+                // handler-scope errors are host dispatch bugs worth surfacing.
+                if (error.scope === 'handler') {
+                    console.error(`[canon-sdk] Runtime control ${error.key ?? 'poll'} dispatch failed for ${error.conversationId}:`, error.error);
+                }
+            },
+        });
+        return this.controlPoller;
+    }
     async baselineRuntimeControlSignals(conversationIds) {
-        if (!this.agentId || !this.hasRuntimeSignalSupport())
+        if (!this.hasRuntimeSignalSupport())
             return;
-        await Promise.all(conversationIds.map(async (conversationId) => {
-            const raw = await Promise.resolve(rtdbRead(`/control/${conversationId}/${this.agentId}/signal`)).catch(() => null);
-            if (!raw || typeof raw !== 'object')
-                return;
-            const timestamp = Number(raw.updatedAt ?? 0);
-            if (timestamp > 0) {
-                this.lastSeenSignal.set(conversationId, timestamp);
-            }
-        }));
+        await this.ensureControlPoller()?.baseline(conversationIds);
     }
     startRuntimeControlPolling() {
-        if (!this.agentId || this.runtimeControlPollTimer || !this.hasRuntimeControlSupport())
+        if (!this.hasRuntimeControlSupport())
             return;
-        this.runtimeControlPollTimer = setInterval(() => {
-            void this.pollRuntimeControls();
-        }, 2_000);
-        this.runtimeControlPollTimer.unref?.();
+        this.ensureControlPoller()?.start();
     }
     stopRuntimeControlPolling() {
-        if (!this.runtimeControlPollTimer)
-            return;
-        clearInterval(this.runtimeControlPollTimer);
-        this.runtimeControlPollTimer = null;
+        this.controlPoller?.stop();
     }
-    async pollRuntimeControls() {
-        if (!this.agentId || !this.hasRuntimeControlSupport())
+    async handleRuntimePrimitiveEvent(event) {
+        // Requests only belong to this runtime once primitive handlers exist —
+        // leave them untouched otherwise (the legacy loop never read the key).
+        if (!this.hasRuntimePrimitiveSupport())
+            return { consume: false };
+        const { conversationId, requestId, value } = event;
+        const primitive = value.id;
+        // Unknown primitives and unhandled ids fall through so the poller
+        // consumes the request without dispatching, matching the legacy loop.
+        if (!isRuntimePrimitiveId(primitive))
             return;
-        await Promise.all(this.cachedConversationIds.map(async (conversationId) => {
-            if (this.hasRuntimeSignalSupport()) {
-                const raw = await Promise.resolve(rtdbRead(`/control/${conversationId}/${this.agentId}/signal`)).catch(() => null);
-                if (raw && typeof raw === 'object') {
-                    await this.handleRuntimeSignal(conversationId, raw);
-                }
-            }
-            if (this.hasRuntimePrimitiveSupport()) {
-                const raw = await Promise.resolve(rtdbRead(`/control/${conversationId}/${this.agentId}/primitive`)).catch(() => null);
-                if (raw && typeof raw === 'object') {
-                    await this.handleRuntimePrimitiveRequests(conversationId, raw);
-                }
-            }
-        }));
-    }
-    async handleRuntimePrimitiveRequests(conversationId, raw) {
-        if (!this.agentId)
+        const handler = this.primitiveHandlers.get(primitive) ?? this.primitiveFallbackHandler;
+        if (!handler)
             return;
-        this.prunePrimitiveRequestDedupe();
-        const requests = Object.entries(raw)
-            .map(([requestId, value]) => ({ requestId, value }))
-            .filter((entry) => (Boolean(entry.requestId)
-            && Boolean(entry.value)
-            && typeof entry.value === 'object'
-            && !Array.isArray(entry.value)))
-            .sort((a, b) => Number(a.value.updatedAt ?? 0) - Number(b.value.updatedAt ?? 0));
-        for (const { requestId, value } of requests) {
-            const requestKey = `${conversationId}:${requestId}`;
-            if (this.primitiveRequestDedupe.has(requestKey))
-                continue;
-            this.primitiveRequestDedupe.set(requestKey, Date.now());
-            let cleared = false;
-            try {
-                const primitive = value.id;
-                if (!isRuntimePrimitiveId(primitive)) {
-                    cleared = await this.clearRuntimePrimitiveRequest(conversationId, requestId);
-                    continue;
-                }
-                const handler = this.primitiveHandlers.get(primitive) ?? this.primitiveFallbackHandler;
-                if (!handler) {
-                    cleared = await this.clearRuntimePrimitiveRequest(conversationId, requestId);
-                    continue;
-                }
-                const args = normalizePrimitiveArgs(value.args);
-                await Promise.resolve(handler({
-                    conversationId,
-                    primitive,
-                    args,
-                    requestId,
-                    updatedAt: typeof value.updatedAt === 'number' ? value.updatedAt : undefined,
-                    rawText: typeof value.rawText === 'string' ? value.rawText : undefined,
-                    alias: typeof value.alias === 'string' ? value.alias : undefined,
-                })).catch((error) => {
-                    console.error(`[canon-sdk] Runtime primitive ${primitive} handler failed for ${conversationId}:`, error);
-                });
-                cleared = await this.clearRuntimePrimitiveRequest(conversationId, requestId);
-            }
-            finally {
-                if (cleared) {
-                    this.primitiveRequestDedupe.delete(requestKey);
-                }
-            }
-        }
-    }
-    async clearRuntimePrimitiveRequest(conversationId, requestId) {
-        if (!this.agentId)
-            return false;
-        try {
-            await Promise.resolve(rtdbWrite(`/control/${conversationId}/${this.agentId}/primitive/${requestId}`, null));
-            return true;
-        }
-        catch {
-            return false;
-        }
-    }
-    prunePrimitiveRequestDedupe(now = Date.now()) {
-        for (const [key, timestamp] of this.primitiveRequestDedupe) {
-            if (now - timestamp >= RUNTIME_PRIMITIVE_DEDUPE_TTL_MS) {
-                this.primitiveRequestDedupe.delete(key);
-            }
-        }
-        while (this.primitiveRequestDedupe.size > RUNTIME_PRIMITIVE_DEDUPE_MAX) {
-            const oldestKey = this.primitiveRequestDedupe.keys().next().value;
-            if (!oldestKey)
-                break;
-            this.primitiveRequestDedupe.delete(oldestKey);
-        }
+        await Promise.resolve(handler({
+            conversationId,
+            primitive,
+            args: normalizePrimitiveArgs(value.args),
+            requestId,
+            updatedAt: typeof value.updatedAt === 'number' ? value.updatedAt : undefined,
+            rawText: typeof value.rawText === 'string' ? value.rawText : undefined,
+            alias: typeof value.alias === 'string' ? value.alias : undefined,
+        })).catch((error) => {
+            console.error(`[canon-sdk] Runtime primitive ${primitive} handler failed for ${conversationId}:`, error);
+        });
     }
-    async handleRuntimeSignal(conversationId, raw) {
-        if (!this.agentId)
-            return;
-        const signal = raw.type;
-        if (signal !== 'interrupt' && signal !== 'stop_and_drop' && signal !== 'new_session')
-            return;
-        const timestamp = Number(raw.updatedAt ?? 0);
-        if (timestamp <= (this.lastSeenSignal.get(conversationId) ?? 0))
-            return;
-        this.lastSeenSignal.set(conversationId, timestamp);
+    async handleRuntimeSignalEvent(event) {
+        // Signals only belong to this runtime once signal handlers exist — leave
+        // them untouched otherwise (the legacy loop never read the key).
+        if (!this.hasRuntimeSignalSupport())
+            return { consume: false };
+        const { conversationId, type: signal, updatedAt } = event;
         const handler = signal === 'new_session'
             ? this.newSessionHandler
             : signal === 'stop_and_drop'
                 ? this.stopAndDropHandler
                 : this.interruptHandler;
-        if (!handler) {
-            await Promise.resolve(rtdbWrite(`/control/${conversationId}/${this.agentId}/signal`, null)).catch(() => { });
+        // No handler for this specific signal: fall through so the poller
+        // consumes the node without dispatching, matching the legacy loop.
+        if (!handler)
             return;
-        }
         const activeTurn = this.firstActiveTurn(conversationId);
         const abortSignal = this.abortActiveTurns(conversationId);
         const droppedMessages = signal === 'new_session'
@@ -986,16 +966,15 @@ export class CanonAgent {
             hasActiveTurn: Boolean(abortSignal),
             droppedCount: droppedMessages.length,
         });
-        await Promise.resolve(handler?.({
+        await Promise.resolve(handler({
             conversationId,
-            signal: signal,
-            updatedAt: timestamp || undefined,
+            signal,
+            updatedAt: updatedAt || undefined,
             abortSignal,
             droppedMessageIds,
         })).catch((error) => {
             console.error(`[canon-sdk] Runtime ${signal} handler failed for ${conversationId}:`, error);
         });
-        await Promise.resolve(rtdbWrite(`/control/${conversationId}/${this.agentId}/signal`, null)).catch(() => { });
     }
     firstActiveTurn(conversationId) {
         const turns = this.activeTurns.get(conversationId);
@@ -1065,6 +1044,13 @@ export class CanonAgent {
             console.error(`[canon-sdk] Runtime interrupt handler failed for ${conversationId}:`, error);
         });
     }
+    /**
+     * Builds a runtime-state publisher bound to this agent's scoped RTDB
+     * handle (captured in start()). Threading the handle keeps every
+     * publish on this agent's own credentials — without it the publisher
+     * would fall back to core's deprecated module-global RTDB client,
+     * where the last-started agent's token wins in multi-agent processes.
+     */
     createRuntimeStatePublisher() {
         if (!this.agentId)
             return null;
@@ -1072,6 +1058,7 @@ export class CanonAgent {
             agentId: this.agentId,
             clientType: this.options.clientType ?? 'generic',
             hostMode: this.options.runtimeControlSurface === 'host',
+            ...(this.rtdbHandle ? { rtdb: this.rtdbHandle } : {}),
         });
     }
     requireRuntimeStatePublisher() {

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 export { CanonAgent } from './canon-agent.js';
-export type { AgentContactsAPI, AgentUsersAPI } from './canon-agent.js';
+export type { AgentContactsAPI, AgentConversationsAPI, AgentUsersAPI } from './canon-agent.js';
 export { ApprovalManager, buildApprovalOutcome, buildApprovalReply, buildApprovalRequest, CanonApiError, DEFAULT_APPROVAL_CONFIG, generateApprovalId, HOST_ADMISSION_ACTION_CAPABILITIES, HOST_ADMISSION_ACTIONS_DISABLED, parseApprovalReplyMetadata, parseApprovalRequestMetadata, parseSessionRule, redactSecrets, } from '@canonmsg/core';
 export type { ApprovalConfig, ApprovalNativeRequestMetadata, ApprovalOutcomeMetadata, ApprovalReplyMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalResult, ApprovalRisk, CanonContact, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeTurnModeActivation, CanonRuntimeTurnModeDescriptor, CanonRuntimeTurnModeScope, CanonRuntimeFact, CanonRuntimeFactGroup, CanonResolveAdmissionResult, ContactAddedPayload, ContactCardPayload, ContactRemovedPayload, ContactSource, HostAdmissionActionCapabilities, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, RuntimeInputAnswers, RuntimeInputChoice, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, SessionRule, } from '@canonmsg/core';
 export { SessionManager } from './session-manager.js';
 export { DEFAULT_MEDIA_CACHE_DIR, getCodexImagePath, getMessageAttachments, inferUploadMimeType, isAnthropicImageAttachment, materializeAttachment, materializeMessageMedia, materializeReplyContextMedia, resolveAttachmentMimeType, sendMediaFileMessage, toAnthropicImageBlock, uploadMediaFile, } from './media.js';
 export type { AnthropicImageBlock, AnthropicImageMimeType, MaterializeMediaOptions, MaterializedCanonAttachment, MaterializedCanonReplyContext, ReplyWithFileOptions, UploadMediaFileOptions, } from './media.js';
 export type { SessionConfig, Session } from './session-manager.js';
-export type { AgentContext, CanonGroupContext, CanonKnownRecentParticipant, CanonMembershipChange, CanonContactRequest, CanonMessage, CanonConversation, CanonReplyContext, CanonSelfContext, CanonTurnContextV2, CanonRuntimeDescriptor, MessageUpdatedPayload, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, CreateConversationOptions, } from '@canonmsg/core';
+export type { AgentContext, CanonGroupContext, CanonKnownRecentParticipant, CanonMembershipChange, CanonContactRequest, CanonMessage, CanonConversation, CanonReplyContext, CanonSelfContext, CanonTurnContextV2, CanonRuntimeDescriptor, MessageUpdatedPayload, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, CreateConversationOptions, CreateConversationResult, DirectSessionSelection, } from '@canonmsg/core';
 export type { CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, ContactRequestHandler, MessageHandler, MessageHandlerContext, MessageUpdatedHandler, ProgressMessageOptions, ProgressMessageResult, ReachOutOptions, ReachOutResult, RuntimeApprovalRequest, RuntimeInputRequest, RuntimeInputResult, RuntimeControlSurface, RuntimePrimitiveContext, RuntimePrimitiveHandler, RuntimePrimitiveHandlers, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';

package/dist/realtime.d.ts

@@ -4,12 +4,21 @@ import { Debouncer } from './debouncer.js';
  * Wraps @canonmsg/core's CanonStream with SDK-specific features:
  * - Debouncer integration (message batching)
  * - Agent context callback
+ * - REST catch-up when the SSE replay window expires (replay.expired)
  */
 export declare class RealtimeManager {
     private debouncer;
     private agentId;
+    private apiClient;
     private stream;
     private running;
+    /** Recent inbound message IDs (`conversationId:messageId`) for cross-flush dedupe. */
+    private readonly recentInboundMessageIds;
+    /** Latest handled inbound message timestamp per conversation. */
+    private readonly lastInboundMessageAtByConversation;
+    /** Lower bound for catch-up in conversations with no in-memory cursor. */
+    private readonly replaySyncStartedAt;
+    private replayCatchupInFlight;
     private lastSseErrorKey;
     private lastSseErrorAt;
     private suppressedSseErrorCount;
@@ -24,6 +33,23 @@ export declare class RealtimeManager {
     private onConnected;
     private onDisconnected;
     constructor(apiKey: string, debouncer: Debouncer, agentId: string, streamUrl?: string, apiClient?: CanonClient);
+    private hasSeenInboundMessage;
+    private recordSeenInboundMessage;
+    private pruneRecentInboundMessageIds;
+    /**
+     * REST catch-up after `replay.expired`: the stream service evicted our
+     * cursor, so messages in the gap were silently dropped. Fetch the newest
+     * page per conversation and feed unseen inbound messages through the normal
+     * debouncer path (same entry point as SSE delivery, same id dedupe).
+     *
+     * Lower bound per conversation: the in-memory last-seen inbound timestamp,
+     * falling back to this manager's construction time for conversations with
+     * no prior inbound traffic — anything older predates this process and may
+     * already have been handled by a previous run. For the same reason the
+     * catch-up is NOT wired on initial connect: with no durable cursor, a fresh
+     * process would re-fire turns for messages an earlier run already answered.
+     */
+    private runReplayCatchup;
     private logSseError;
     setOnAgentContext(cb: (ctx: AgentContext) => void): void;
     setContactRequestHandlers(handlers: {

package/dist/realtime.js

@@ -1,14 +1,39 @@
 import { CanonStream, } from '@canonmsg/core';
+import { shouldDispatchInboundMessage } from './turn-filter.js';
+const RECENT_INBOUND_TTL_MS = 30 * 60 * 1000;
+const MAX_RECENT_INBOUND_MESSAGE_IDS = 5000;
+/**
+ * Newest-page bound for the replay-expiry REST catch-up. The SDK has no
+ * durable per-conversation cursor (everything here is in-memory), so the
+ * catch-up only inspects the newest page per conversation and relies on the
+ * id-based dedupe below for anything that overlaps live SSE delivery.
+ */
+const REPLAY_CATCHUP_PAGE_LIMIT = 50;
+function messageCreatedAtMs(createdAt) {
+    if (!createdAt)
+        return 0;
+    const parsed = new Date(createdAt).getTime();
+    return Number.isFinite(parsed) ? parsed : 0;
+}
 /**
  * Wraps @canonmsg/core's CanonStream with SDK-specific features:
  * - Debouncer integration (message batching)
  * - Agent context callback
+ * - REST catch-up when the SSE replay window expires (replay.expired)
  */
 export class RealtimeManager {
     debouncer;
     agentId;
+    apiClient;
     stream;
     running = false;
+    /** Recent inbound message IDs (`conversationId:messageId`) for cross-flush dedupe. */
+    recentInboundMessageIds = new Map();
+    /** Latest handled inbound message timestamp per conversation. */
+    lastInboundMessageAtByConversation = new Map();
+    /** Lower bound for catch-up in conversations with no in-memory cursor. */
+    replaySyncStartedAt = Date.now();
+    replayCatchupInFlight = null;
     lastSseErrorKey = null;
     lastSseErrorAt = 0;
     suppressedSseErrorCount = 0;
@@ -25,13 +50,19 @@ export class RealtimeManager {
     constructor(apiKey, debouncer, agentId, streamUrl, apiClient) {
         this.debouncer = debouncer;
         this.agentId = agentId;
-        void apiClient;
+        this.apiClient = apiClient ?? null;
         this.stream = new CanonStream({
             apiKey,
             agentId,
             streamUrl,
             handler: {
                 onMessage: (payload) => {
+                    // Cross-flush id dedupe: replay overlap or a concurrent REST
+                    // catch-up 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, messageCreatedAtMs(payload.message.createdAt));
                     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;
@@ -96,12 +127,108 @@ export class RealtimeManager {
                 onDisconnected: () => {
                     this.onDisconnected?.();
                 },
+                onReplayExpired: (payload) => {
+                    console.error(`[canon-sdk] SSE replay window expired${payload.lastAvailableId ? ` (oldest available event: ${payload.lastAvailableId})` : ''} — catching up over REST`);
+                    this.replayCatchupInFlight ??= this.runReplayCatchup().finally(() => {
+                        this.replayCatchupInFlight = null;
+                    });
+                },
                 onError: (err) => {
                     this.logSseError(err);
                 },
             },
         });
     }
+    hasSeenInboundMessage(conversationId, messageId) {
+        return this.recentInboundMessageIds.has(`${conversationId}:${messageId}`);
+    }
+    recordSeenInboundMessage(conversationId, messageId, createdAtMs) {
+        const now = Date.now();
+        this.recentInboundMessageIds.set(`${conversationId}:${messageId}`, now);
+        const effectiveTimestamp = createdAtMs > 0 ? createdAtMs : now;
+        const previous = this.lastInboundMessageAtByConversation.get(conversationId) ?? 0;
+        if (effectiveTimestamp > previous) {
+            this.lastInboundMessageAtByConversation.set(conversationId, effectiveTimestamp);
+        }
+        this.pruneRecentInboundMessageIds(now);
+    }
+    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);
+        }
+    }
+    /**
+     * REST catch-up after `replay.expired`: the stream service evicted our
+     * cursor, so messages in the gap were silently dropped. Fetch the newest
+     * page per conversation and feed unseen inbound messages through the normal
+     * debouncer path (same entry point as SSE delivery, same id dedupe).
+     *
+     * Lower bound per conversation: the in-memory last-seen inbound timestamp,
+     * falling back to this manager's construction time for conversations with
+     * no prior inbound traffic — anything older predates this process and may
+     * already have been handled by a previous run. For the same reason the
+     * catch-up is NOT wired on initial connect: with no durable cursor, a fresh
+     * process would re-fire turns for messages an earlier run already answered.
+     */
+    async runReplayCatchup() {
+        const apiClient = this.apiClient;
+        if (!apiClient) {
+            console.error('[canon-sdk] Replay catch-up skipped — no API client available');
+            return;
+        }
+        try {
+            const conversations = await apiClient.getConversations();
+            let recovered = 0;
+            await Promise.all(conversations.map(async (conversation) => {
+                try {
+                    const page = await apiClient.getMessagesPage(conversation.id, REPLAY_CATCHUP_PAGE_LIMIT);
+                    const lowerBoundMs = this.lastInboundMessageAtByConversation.get(conversation.id)
+                        ?? this.replaySyncStartedAt;
+                    const candidates = [...(page.messages ?? [])]
+                        .filter((message) => !message.deleted)
+                        .sort((a, b) => messageCreatedAtMs(a.createdAt) - messageCreatedAtMs(b.createdAt));
+                    for (const message of candidates) {
+                        if (!this.running)
+                            return;
+                        if (message.senderId === this.agentId)
+                            continue;
+                        const createdAtMs = messageCreatedAtMs(message.createdAt);
+                        if (!createdAtMs || createdAtMs <= lowerBoundMs)
+                            continue;
+                        if (this.hasSeenInboundMessage(conversation.id, message.id))
+                            continue;
+                        this.recordSeenInboundMessage(conversation.id, message.id, createdAtMs);
+                        const dispatch = await shouldDispatchInboundMessage(conversation.id, this.agentId, message, {
+                            conversationType: conversation.type,
+                            behavior: page.behavior ?? null,
+                        });
+                        if (!dispatch)
+                            continue;
+                        this.debouncer.add(conversation.id, message, null);
+                        recovered += 1;
+                    }
+                }
+                catch (err) {
+                    console.error(`[canon-sdk] Replay catch-up failed for ${conversation.id}:`, err instanceof Error ? err.message : err);
+                }
+            }));
+            if (recovered > 0) {
+                console.error(`[canon-sdk] Replay catch-up recovered ${recovered} missed message(s)`);
+            }
+        }
+        catch (err) {
+            console.error('[canon-sdk] Replay catch-up failed:', err instanceof Error ? err.message : err);
+        }
+    }
     logSseError(err) {
         const code = err.code;
         const key = `${typeof code === 'string' ? code : 'generic'}:${err.message}`;

package/dist/types.d.ts

@@ -1,5 +1,5 @@
-export type { AddMemberResult, AgentClientType, CanonGroupContext, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeDescriptor, CanonRuntimeFact, CanonRuntimeFactGroup, CanonRuntimePrimitiveId, CanonRuntimeProvenance, CanonTurnContextV2, CanonMessage, CanonConversation, CanonReplyContext, CanonContact, CanonContactRequest, CanonResolveAdmissionResult, ContactAddedPayload, ContactRemovedPayload, ContactSource, AgentContext, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonSelfContext, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, SessionConfig, CreateConversationOptions, TurnLifecycleState, TurnOutputBlock, TurnOutputBlockInput, ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalRisk, ApprovalReplyMetadata, ApprovalOutcomeMetadata, RuntimeInputChoice, RuntimeInputAnswers, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, RuntimeCardNativeMetadata, RuntimeCardV1, SessionRule, ApprovalResult, } from '@canonmsg/core';
-import type { AddMemberResult, CanonGroupContext, CanonMessage, CanonConversation, CanonReplyContext, ContactCardPayload, CanonRuntimeActionDispatch, CanonRuntimePrimitiveId, CanonRuntimeProvenance, CanonTurnContextV2, ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalResult, ApprovalRisk, RuntimeInputChoice, RuntimeInputAnswers, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, RuntimeCardNativeMetadata, RuntimeCardV1, SendMessageOptions, SendContextualSelfContextInput, SessionConfig, TurnOutputBlock, TurnOutputBlockInput } from '@canonmsg/core';
+export type { AddMemberResult, AgentClientType, CanonGroupContext, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeDescriptor, CanonRuntimeFact, CanonRuntimeFactGroup, CanonRuntimePrimitiveId, CanonRuntimeProvenance, CanonTurnContextV2, CanonMessage, CanonConversation, CanonReplyContext, CanonContact, CanonContactRequest, CanonResolveAdmissionResult, ContactAddedPayload, ContactRemovedPayload, ContactSource, AgentContext, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonSelfContext, CreateConversationResult, DirectSessionSelection, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, SessionConfig, CreateConversationOptions, TurnLifecycleState, TurnOutputBlock, TurnOutputBlockInput, ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalRisk, ApprovalReplyMetadata, ApprovalOutcomeMetadata, RuntimeInputChoice, RuntimeInputAnswers, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, RuntimeCardNativeMetadata, RuntimeCardV1, SessionRule, ApprovalResult, } from '@canonmsg/core';
+import type { AddMemberResult, CanonGroupContext, CanonMessage, CanonConversation, CanonReplyContext, ContactCardPayload, CanonRuntimeActionDispatch, CanonRuntimePrimitiveId, CanonRuntimeProvenance, CanonTurnContextV2, ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalResult, ApprovalRisk, RuntimeInputChoice, RuntimeInputAnswers, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, RuntimeCardNativeMetadata, RuntimeCardV1, SendMessageOptions, SendContextualSelfContextInput, SessionConfig, DirectSessionSelection, TurnOutputBlock, TurnOutputBlockInput } from '@canonmsg/core';
 import type { MaterializeMediaOptions, MaterializedCanonAttachment, ReplyWithFileOptions, UploadMediaFileOptions } from './media.js';
 export interface ProgressMessageOptions extends SendMessageOptions {
     /**
@@ -282,6 +282,9 @@ export type ReachOutResult = {
     conversationId: string;
     messageId?: string;
     selfContextId?: string;
+    created?: boolean;
+    reused?: boolean;
+    sessionSelection?: DirectSessionSelection['mode'];
 } | {
     status: 'requested';
     requestId: string | null;
@@ -293,6 +296,9 @@ export type ReachOutResult = {
 } | {
     status: 'setup_required';
     reason: string;
+} | {
+    status: 'no_session';
+    reason: string;
 } | {
     status: 'blocked' | 'unavailable';
     reason: string;
@@ -304,6 +310,8 @@ export interface ReachOutOptions {
     requestMessage?: string;
     /** Explicit session setup to use when the contact-card target is an agent. */
     sessionConfig?: SessionConfig | null;
+    /** Whether to continue an existing direct agent session or start a fresh one. */
+    sessionSelection?: DirectSessionSelection;
     /** Source conversation for contextual cross-session reach-outs. */
     sourceConversationId?: string;
     /** Private context for the agent when this reach-out sends a cross-session message. */

package/package.json

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