@canonmsg/agent-sdk 10.2.1 → 10.4.0

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, 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, 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';
@@ -143,6 +143,9 @@ const STANDARD_PRIMITIVE_COMMANDS = {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function knownMembershipRevision(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
 function sleepWithAbort(ms, signal) {
     if (signal.aborted)
         return Promise.reject(createTurnAbortError());
@@ -325,6 +328,7 @@ export class CanonAgent {
     activeAbortControllers = new Map();
     activeTurns = new Map();
     conversationMemberIds = new Map();
+    conversationMembershipRevisions = new Map();
     pendingMembershipChanges = new Map();
     typingSignals;
     sseConnectedLogged = false;
@@ -964,24 +968,43 @@ export class CanonAgent {
     }
     rememberConversationMembers(conversations) {
         for (const conversation of conversations) {
+            const revision = knownMembershipRevision(conversation.membershipRevision);
+            const currentRevision = this.conversationMembershipRevisions.get(conversation.id);
+            if (revision !== undefined && currentRevision !== undefined && revision < currentRevision)
+                continue;
             this.conversationMemberIds.set(conversation.id, [...(conversation.memberIds ?? [])]);
+            if (revision !== undefined)
+                this.conversationMembershipRevisions.set(conversation.id, revision);
+            else
+                this.conversationMembershipRevisions.delete(conversation.id);
         }
     }
     handleConversationUpdated(payload) {
         const rawMemberIds = payload.changes.memberIds;
         if (!Array.isArray(rawMemberIds))
             return;
+        const revision = knownMembershipRevision(payload.changes.membershipRevision);
+        const currentRevision = this.conversationMembershipRevisions.get(payload.conversationId);
+        if (revision !== undefined && currentRevision !== undefined && revision < currentRevision)
+            return;
         const memberIds = rawMemberIds.filter((id) => typeof id === 'string');
         const hadPreviousMemberIds = this.conversationMemberIds.has(payload.conversationId);
         const previousMemberIds = this.conversationMemberIds.get(payload.conversationId) ?? [];
         const membershipChange = payload.membershipChange
             ?? (hadPreviousMemberIds ? diffCanonMemberIds(previousMemberIds, memberIds) : null);
         this.conversationMemberIds.set(payload.conversationId, memberIds);
+        if (revision !== undefined)
+            this.conversationMembershipRevisions.set(payload.conversationId, revision);
+        else
+            this.conversationMembershipRevisions.delete(payload.conversationId);
         if (membershipChange) {
             this.pendingMembershipChanges.set(payload.conversationId, membershipChange);
         }
         if (this.agentId && !memberIds.includes(this.agentId)) {
             this.cachedConversationIds = this.cachedConversationIds.filter((id) => id !== payload.conversationId);
+            this.abortActiveTurns(payload.conversationId);
+            this.sessionManager?.dropQueued(payload.conversationId);
+            this.pendingMembershipChanges.delete(payload.conversationId);
         }
         else {
             this.rememberConversationId(payload.conversationId);
@@ -1254,7 +1277,53 @@ export class CanonAgent {
     async executeHandler(conversationId, messages, session, provenanceByMessageId) {
         if (!this.handler)
             return;
+        // Message rediscovery can precede the SSE roster snapshot after admission.
+        // Refresh before trusting cached exclusion, accepting queued input, or
+        // freezing output policy. Reuse this same snapshot for handler context.
+        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;
+            }
+        }
+        let conversation = conversations.find((c) => c.id === conversationId);
+        if (!conversation)
+            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]);
+        }
+        const currentMembers = this.conversationMemberIds.get(conversationId);
+        if (currentMembers && this.agentId && !currentMembers.includes(this.agentId))
+            return;
+        this.rememberConversationId(conversationId);
         await this.markQueuedMessagesAccepted(conversationId, messages);
+        const acceptedMembers = this.conversationMemberIds.get(conversationId);
+        if (acceptedMembers && this.agentId && !acceptedMembers.includes(this.agentId))
+            return;
         const turnId = randomUUID();
         const turnOpenedAt = Date.now();
         let turnState = 'thinking';
@@ -1316,19 +1385,14 @@ export class CanonAgent {
                     : {}),
             })).catch(() => { });
         };
-        // Quiet mode is resolved HERE, once, and carried for the whole turn.
-        //
-        // It has to be here because everything downstream is already too late: the
-        // controller's mode is fixed at construction two lines below, the
-        // `'Thinking...'` seed lands before that, and the conversation fetch that
-        // would otherwise name the conversation type is ~30 lines further down,
-        // inside the try. Provenance already carries the type — the stream service
-        // stamps it on every `message.created` frame — so the answer is available
-        // before the first publish of any kind.
-        //
-        // Re-deriving it mid-turn is what must never happen: a turn that started
-        // quiet and finished verbose would emit a trail nothing narrated.
-        const inboundConversationType = normalizeTurnVerbosityConversationType(provenanceByMessageId?.get(triggeringMessageId ?? '')?.conversation?.type);
+        // Resolve once from the refreshed roster before constructing the output
+        // controller or publishing the first thinking seed. Keep it fixed for the
+        // turn so the final trail agrees with what was actually narrated.
+        const inboundProvenance = provenanceByMessageId?.get(triggeringMessageId ?? '')?.conversation;
+        const inboundRoster = this.conversationMemberIds.get(conversationId) ?? inboundProvenance?.memberCount;
+        const inboundConversationType = inboundRoster != null
+            ? resolveConversationPolicyScope(inboundRoster)
+            : normalizeTurnVerbosityConversationType(inboundProvenance?.type);
         const turnVerbosity = resolveTurnVerbosity({
             configured: selectConfiguredTurnVerbosity(this.options.turnVerbosity, inboundConversationType),
             conversationType: inboundConversationType,
@@ -1412,12 +1476,6 @@ export class CanonAgent {
             if (this.sessionManager && session) {
                 this.sessionManager.seedHistory(conversationId, history);
             }
-            // Get conversation info
-            const conversations = await this.apiClient.getConversations();
-            this.rememberConversationMembers(conversations);
-            const conversation = conversations.find((c) => c.id === conversationId);
-            if (!conversation)
-                return;
             // Build reply functions
             const replyFinal = async (text, options) => {
                 throwIfAborted();
@@ -1615,7 +1673,7 @@ export class CanonAgent {
                 ? resolveRuntimeProvenance({
                     provenance: provenanceByMessageId?.get(latestMessage.id) ?? null,
                     conversationId,
-                    conversationType: conversation.type,
+                    conversationType: resolveConversationPolicyScope(conversation.memberIds),
                     memberCount: conversation.memberIds.length,
                     senderId: latestMessage.senderId,
                     senderName: latestMessage.senderName ?? latestMessage.senderId,
@@ -1628,7 +1686,7 @@ export class CanonAgent {
                 })
                 : resolveRuntimeProvenance({
                     conversationId,
-                    conversationType: conversation.type,
+                    conversationType: resolveConversationPolicyScope(conversation.memberIds),
                     memberCount: conversation.memberIds.length,
                     senderId: '',
                     senderType: 'human',
@@ -1663,7 +1721,7 @@ export class CanonAgent {
                 content: latestMessage ? renderCanonHostInboundContent(latestMessage) : '[Empty message]',
                 conversationId,
                 participantContext: {
-                    conversationType: conversation.type,
+                    conversationType: resolveConversationPolicyScope(conversation.memberIds),
                     memberCount: conversation.memberIds.length,
                     senderType: latestMessage?.senderType ?? provenance.sender.type,
                     senderName: latestMessage?.senderName

package/dist/index.d.ts

@@ -11,3 +11,11 @@ export type { SessionConfig, Session } from './session-manager.js';
 export type { CanonAgentTurnVerbosityOption } from './turn-verbosity-option.js';
 export type { AgentContext, CanonGroupContext, CanonKnownRecentParticipant, CanonMembershipChange, CanonMessage, CanonConversation, CommunicateInput, CommunicateResult, DirectConversationSelection, CanonConversationsPage, CanonConversationsPageOptions, CanonReplyContext, CanonSelfContext, CanonTurnContextV2, CanonRuntimeDescriptor, MessageUpdatedPayload, SendMessageOptions, CreateGroupOptions, CreateGroupResult, TurnVerbosity, TurnVerbosityConfig, } from '@canonmsg/core';
 export type { CanonAgentConnectionOptions, CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, FinalMessageResult, MessageHandler, MessageHandlerContext, MessageUpdatedHandler, ParticipationSuppressedHandler, ProgressMessageOptions, ProgressMessageResult, RuntimeApprovalRequest, RuntimeInputRequest, RuntimeInputResult, RuntimePlanReviewRequest, RuntimePlanReviewResult, RuntimeControlSurface, RuntimePrimitiveContext, RuntimePrimitiveHandler, RuntimePrimitiveHandlers, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';
+export { createCanonAttachedSession, createCanonAttachedSessionPublisher } from './attached-session.js';
+export { createCanonWorkSessionHost } from './work-session-host.js';
+export type { CanonWorkSessionHost, CanonWorkSessionHostOptions } from './work-session-host.js';
+export { createFileWorkSessionHostStore } from './work-session-state.js';
+export type { WorkSessionHostStore, WorkSessionHostJournal } from './work-session-state.js';
+export { createFileAttachedSessionStore } from '@canonmsg/core';
+export type { CanonAttachedSession, CanonAttachedSessionConnection, CanonAttachedSessionOptions, CanonAttachedSessionStatus, } from './attached-session.js';
+export type { AttachedNativeSessionAdapter, AttachedSessionBinding, AttachedSessionJournal, AttachedSessionState, AttachedSessionStore, NativeSessionEvent, NativeSessionItem, NativeSessionSnapshot, NativeSubmissionResult, } from '@canonmsg/core';

package/dist/index.js

@@ -3,3 +3,7 @@ export { clearPendingRegistration, ensureAgentProfile, resumeRegistration } from
 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 { SessionManager } from './session-manager.js';
 export { DEFAULT_ANTHROPIC_REQUEST_HEADROOM_BYTES, DEFAULT_MEDIA_CACHE_DIR, DEFAULT_MEDIA_MATERIALIZATION_BYTES, MAX_ANTHROPIC_IMAGE_RAW_BYTES, MAX_ANTHROPIC_REQUEST_BYTES, MAX_CANON_MEDIA_BYTES, getCodexImagePath, getMessageAttachments, inferUploadMimeType, isAnthropicImageAttachment, materializeAttachment, materializeMessageMedia, materializeReplyContextMedia, resolveAttachmentMimeType, sendMediaFileMessage, toAnthropicImageBlock, toAnthropicImageBlocksWithinBudget, uploadMediaFile, } from './media.js';
+export { createCanonAttachedSession, createCanonAttachedSessionPublisher } from './attached-session.js';
+export { createCanonWorkSessionHost } from './work-session-host.js';
+export { createFileWorkSessionHostStore } from './work-session-state.js';
+export { createFileAttachedSessionStore } from '@canonmsg/core';

package/dist/media.d.ts

@@ -22,6 +22,12 @@ export interface UploadMediaFileOptions {
     signal?: AbortSignal;
 }
 export interface ReplyWithFileOptions extends Omit<SendMessageOptions, 'attachments' | 'contentType'>, UploadMediaFileOptions {
+    /**
+     * Optional local policy check after upload/finalization, immediately before
+     * publishing the attachment. Returning false withholds the message. Automatic
+     * artifact routing uses this to recheck its current audience.
+     */
+    canPublish?: () => boolean;
 }
 export interface MaterializedCanonAttachment extends MediaAttachment {
     index: number;

package/dist/media.js

@@ -396,7 +396,7 @@ export async function uploadMediaFile(client, conversationId, filePath, options)
     return uploaded;
 }
 export async function sendMediaFileMessage(client, conversationId, filePath, text = '', options) {
-    const { fileName, mimeType, durationMs, fetchImpl, signal, ...sendOptions } = options ?? {};
+    const { fileName, mimeType, durationMs, fetchImpl, signal, canPublish, ...sendOptions } = options ?? {};
     const uploaded = await uploadMediaFile(client, conversationId, filePath, {
         ...(fileName ? { fileName } : {}),
         ...(mimeType ? { mimeType } : {}),
@@ -405,6 +405,9 @@ export async function sendMediaFileMessage(client, conversationId, filePath, tex
         ...(signal ? { signal } : {}),
     });
     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,

package/dist/work-session-host.d.ts

@@ -0,0 +1,31 @@
+import { type AttachedSessionBinding, type AttachedSessionStore, type NativeWorkSessionProvider } from '@canonmsg/core';
+import { type CanonAttachedSessionConnection, type CanonAttachedSessionStatus } from './attached-session.js';
+import { type WorkSessionHostStore } from './work-session-state.js';
+export interface CanonWorkSessionHostOptions {
+    connection: CanonAttachedSessionConnection;
+    /** Stable installation identity. A new random runtime epoch is used each start. */
+    hostId: string;
+    displayName: string;
+    provider: NativeWorkSessionProvider;
+    store: WorkSessionHostStore;
+    createSessionStore(binding: AttachedSessionBinding): AttachedSessionStore;
+    /** Process-wide native audience lock, shared with any standalone attachment CLI. */
+    acquireNativeSession(binding: AttachedSessionBinding): (() => void) | Promise<() => void>;
+    onStatus?: (event: {
+        status: 'available' | 'stopped' | 'session';
+        conversationId?: string;
+        session?: CanonAttachedSessionStatus;
+    }) => void;
+    onError?: (error: unknown, operation: string) => void;
+    pollIntervalMs?: number;
+    heartbeatIntervalMs?: number;
+    connectTimeoutMs?: number;
+}
+export interface CanonWorkSessionHost {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** Refresh discovery and process one durable request; serialized with the poll loop. */
+    reconcile(): Promise<void>;
+}
+/** One authenticated transport and liveness publisher, with durable per-room native routes. */
+export declare function createCanonWorkSessionHost(options: CanonWorkSessionHostOptions): CanonWorkSessionHost;