@canonmsg/agent-sdk 1.4.0 → 1.5.0

package/README.md

@@ -130,6 +130,7 @@ Current rules of thumb:
 - `selectionPolicy: 'required_explicit'` means Canon should require the user to make a choice instead of silently inheriting a default
 - `workspaceRoots` and `writableRoots` document allowed roots and let Canon group project choices. Canon still stores the selected concrete `workspaceId`; it does not send arbitrary root-relative paths to generic SDK agents.
 - Publishing a descriptor does not automatically make your SDK agent enforce those controls. If you advertise model, workspace, execution mode, or runtime-native controls, your runtime must actually read and apply the stored config.
+- Message handlers receive `ctx.provenance`, a Canon-computed sender/conversation context for the latest inbound message in the batch. Use it when your runtime wants owner-only tools, group mention policy, or self-context-aware behavior; Canon does not impose a sandbox on SDK agents.
 
 ## Delivery Modes
 

package/dist/canon-agent.d.ts

@@ -42,6 +42,9 @@ export declare class CanonAgent {
     private readonly reachOutInFlight;
     private agentId;
     private agentContext;
+    private approvalManager;
+    private approvalManagerAgentId;
+    private approvalManagerOwnerId;
     private cachedConversationIds;
     private running;
     private runtimeHeartbeatTimer;
@@ -49,9 +52,12 @@ export declare class CanonAgent {
     private readonly lastSeenSignal;
     private readonly primitiveRequestDedupe;
     private readonly activeAbortControllers;
+    private readonly activeTurns;
     private readonly conversationMemberIds;
     private readonly pendingMembershipChanges;
     constructor(options: CanonAgentOptions);
+    private ensureApprovalManager;
+    private filterApprovalReplyMessages;
     on(event: 'message', handler: MessageHandler): void;
     on(event: 'contactRequest', handler: ContactRequestHandler): void;
     on(event: 'contactApproved', handler: ContactRequestHandler): void;
@@ -128,6 +134,8 @@ export declare class CanonAgent {
     private clearRuntimePrimitiveRequest;
     private prunePrimitiveRequestDedupe;
     private handleRuntimeSignal;
+    private firstActiveTurn;
+    private publishAcceptedRuntimeSignal;
     private abortActiveTurns;
     private resolveBatchDeliveryIntent;
     private notifyMessageInterrupt;

package/dist/canon-agent.js

@@ -1,8 +1,8 @@
-import { CanonClient, buildCanonGroupContext, createRuntimeStatePublisher, diffCanonMemberIds, FINAL_MESSAGE_HANDOFF_MS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, initRTDBAuth, rtdbRead, rtdbWrite, normalizeTurnMetadata, reachOutToCanonContact, resolveMessageActiveSelfContextId, selectActiveSelfContexts, } from '@canonmsg/core';
+import { ApprovalManager, CanonClient, buildCanonGroupContext, createRuntimeStatePublisher, diffCanonMemberIds, FINAL_MESSAGE_HANDOFF_MS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, initRTDBAuth, rtdbRead, rtdbWrite, normalizeTurnMetadata, reachOutToCanonContact, resolveCanonReplyContext, resolveMessageActiveSelfContextId, resolveRuntimeProvenance, selectActiveSelfContexts, } from '@canonmsg/core';
 import { randomUUID } from 'node:crypto';
 import { AuthManager } from './auth.js';
 import { Debouncer } from './debouncer.js';
-import { materializeMessageMedia, sendMediaFileMessage, uploadMediaFile, } from './media.js';
+import { materializeMessageMedia, materializeReplyContextMedia, sendMediaFileMessage, uploadMediaFile, } from './media.js';
 import { SessionManager } from './session-manager.js';
 const AGENT_RUNTIME_HEARTBEAT_MS = 30_000;
 const RUNTIME_PRIMITIVE_DEDUPE_TTL_MS = 5 * 60 * 1000;
@@ -168,6 +168,19 @@ function normalizeRuntimeActivityItem(item) {
         updatedAt: item.updatedAt || Date.now(),
     };
 }
+function createTurnAbortError() {
+    const error = new Error('Canon turn was interrupted before reply delivery.');
+    error.name = 'AbortError';
+    return error;
+}
+function isAbortLikeError(error) {
+    if (!error || typeof error !== 'object')
+        return false;
+    const record = error;
+    if (record.name === 'AbortError' || record.code === 'ABORT_ERR')
+        return true;
+    return typeof record.message === 'string' && /\babort(?:ed)?\b/i.test(record.message);
+}
 export class CanonAgent {
     options;
     apiClient;
@@ -192,6 +205,9 @@ export class CanonAgent {
     reachOutInFlight = new Map();
     agentId = null;
     agentContext = null;
+    approvalManager = null;
+    approvalManagerAgentId = null;
+    approvalManagerOwnerId = null;
     cachedConversationIds = [];
     running = false;
     runtimeHeartbeatTimer = null;
@@ -199,6 +215,7 @@ export class CanonAgent {
     lastSeenSignal = new Map();
     primitiveRequestDedupe = new Map();
     activeAbortControllers = new Map();
+    activeTurns = new Map();
     conversationMemberIds = new Map();
     pendingMembershipChanges = new Map();
     constructor(options) {
@@ -243,6 +260,47 @@ export class CanonAgent {
             }
         }
     }
+    ensureApprovalManager(agentContext = this.agentContext) {
+        const agentId = agentContext?.agentId || this.agentId;
+        const ownerId = agentContext?.ownerId;
+        if (!agentId || !ownerId)
+            return null;
+        if (this.approvalManager
+            && this.approvalManagerAgentId === agentId
+            && this.approvalManagerOwnerId === ownerId) {
+            return this.approvalManager;
+        }
+        if (this.approvalManager?.pendingCount) {
+            return this.approvalManager;
+        }
+        this.approvalManager?.dispose();
+        this.approvalManager = new ApprovalManager(this.apiClient, agentId, ownerId);
+        this.approvalManagerAgentId = agentId;
+        this.approvalManagerOwnerId = ownerId;
+        return this.approvalManager;
+    }
+    filterApprovalReplyMessages(conversationId, messages) {
+        const manager = this.ensureApprovalManager();
+        if (!manager) {
+            return messages.filter((message) => {
+                const metadata = message.metadata;
+                return !(metadata && typeof metadata === 'object' && !Array.isArray(metadata)
+                    && metadata.type === 'approval_reply');
+            });
+        }
+        return messages.filter((message) => {
+            const metadata = message.metadata;
+            const metadataRecord = metadata && typeof metadata === 'object' && !Array.isArray(metadata)
+                ? metadata
+                : null;
+            const consumed = manager.handleMessage(conversationId, {
+                senderId: message.senderId,
+                ...(typeof message.text === 'string' ? { text: message.text } : {}),
+                ...(metadataRecord ? { metadata: metadataRecord } : {}),
+            });
+            return !consumed && metadataRecord?.type !== 'approval_reply';
+        });
+    }
     on(event, handler) {
         if (event === 'message') {
             this.handler = handler;
@@ -397,9 +455,9 @@ export class CanonAgent {
         this.agentId = agentId;
         console.log(`[canon-sdk] Authenticated as ${agentId}`);
         // 2. Wire debouncer to handler
-        this.debouncer.setCallback(async (conversationId, messages) => {
+        this.debouncer.setCallback(async (conversationId, messages, provenanceByMessageId) => {
             this.rememberConversationId(conversationId);
-            await this.handleMessages(conversationId, messages);
+            await this.handleMessages(conversationId, messages, provenanceByMessageId);
         });
         // 3. Fetch conversations (used for delivery mode + session state)
         let conversations = [];
@@ -423,6 +481,7 @@ export class CanonAgent {
         // 3b. Fetch agent context (identity, owner, access level)
         try {
             this.agentContext = await this.apiClient.getAgentMe();
+            this.ensureApprovalManager(this.agentContext);
         }
         catch {
             console.warn('[canon-sdk] Failed to fetch agent context — owner/access info unavailable');
@@ -448,6 +507,7 @@ export class CanonAgent {
         const rtm = new RealtimeManager(this.options.apiKey, this.debouncer, agentId, this.options.streamUrl, this.apiClient);
         rtm.setOnAgentContext((ctx) => {
             this.agentContext = ctx;
+            this.ensureApprovalManager(ctx);
         });
         rtm.setContactRequestHandlers({
             onContactRequest: (request) => {
@@ -832,6 +892,7 @@ export class CanonAgent {
             await Promise.resolve(rtdbWrite(`/control/${conversationId}/${this.agentId}/signal`, null)).catch(() => { });
             return;
         }
+        const activeTurn = this.firstActiveTurn(conversationId);
         const abortSignal = this.abortActiveTurns(conversationId);
         const droppedMessages = signal === 'new_session'
             ? this.sessionManager?.resetSession(conversationId) ?? []
@@ -844,6 +905,10 @@ export class CanonAgent {
                 return Promise.resolve();
             return this.apiClient.updateMessageDisposition(conversationId, message.id, 'rejected').catch(() => { });
         }));
+        await this.publishAcceptedRuntimeSignal(conversationId, signal, activeTurn, {
+            hasActiveTurn: Boolean(abortSignal),
+            droppedCount: droppedMessages.length,
+        });
         await Promise.resolve(handler?.({
             conversationId,
             signal: signal,
@@ -855,6 +920,39 @@ export class CanonAgent {
         });
         await Promise.resolve(rtdbWrite(`/control/${conversationId}/${this.agentId}/signal`, null)).catch(() => { });
     }
+    firstActiveTurn(conversationId) {
+        const turns = this.activeTurns.get(conversationId);
+        if (!turns || turns.size === 0)
+            return null;
+        return turns.values().next().value ?? null;
+    }
+    async publishAcceptedRuntimeSignal(conversationId, signal, activeTurn, outcome) {
+        if (!this.agentId)
+            return;
+        const shouldPublishInterrupted = signal === 'interrupt'
+            || signal === 'stop_and_drop'
+            || outcome.hasActiveTurn
+            || outcome.droppedCount > 0;
+        const runtimeState = shouldPublishInterrupted
+            ? this.createRuntimeStatePublisher()
+            : null;
+        if (runtimeState) {
+            await Promise.resolve(runtimeState.writeTurnState(conversationId, {
+                turnId: activeTurn?.turnId ?? null,
+                state: 'interrupted',
+                queueDepth: this.sessionManager?.getQueueDepth(conversationId) ?? 0,
+                currentSpeakerId: this.agentId,
+                activeMessageIds: activeTurn?.activeMessageIds ?? [],
+                capabilities: this.buildRuntimeCapabilities(),
+                ...(activeTurn?.openedAt ? { openedAt: activeTurn.openedAt } : {}),
+                completedAt: { '.sv': 'timestamp' },
+            })).catch(() => { });
+        }
+        await Promise.all([
+            this.apiClient.clearStreaming(conversationId).catch(() => { }),
+            this.apiClient.setTyping(conversationId, false).catch(() => { }),
+        ]);
+    }
     abortActiveTurns(conversationId) {
         const controllers = this.activeAbortControllers.get(conversationId);
         if (!controllers || controllers.size === 0)
@@ -898,7 +996,12 @@ export class CanonAgent {
         }
         return publisher;
     }
-    async handleMessages(conversationId, messages) {
+    async handleMessages(conversationId, messages, provenanceByMessageId) {
+        const actionableMessages = this.filterApprovalReplyMessages(conversationId, messages);
+        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.`);
             return;
@@ -909,14 +1012,14 @@ export class CanonAgent {
         await this.notifyMessageInterrupt(conversationId, abortSignal);
         if (this.sessionManager) {
             await this.sessionManager.enqueue(conversationId, messages, async (session, newMessages) => {
-                await this.executeHandler(conversationId, newMessages, session);
+                await this.executeHandler(conversationId, newMessages, session, provenanceByMessageId);
             }, { toFront: shouldInterrupt });
         }
         else {
-            await this.executeHandler(conversationId, messages);
+            await this.executeHandler(conversationId, messages, undefined, provenanceByMessageId);
         }
     }
-    async executeHandler(conversationId, messages, session) {
+    async executeHandler(conversationId, messages, session, provenanceByMessageId) {
         if (!this.handler)
             return;
         const turnId = randomUUID();
@@ -927,9 +1030,21 @@ export class CanonAgent {
         const runtimeState = this.createRuntimeStatePublisher();
         const queueDepth = () => this.sessionManager?.getQueueDepth(conversationId) ?? 0;
         const abortController = new AbortController();
+        const throwIfAborted = () => {
+            if (abortController.signal.aborted) {
+                throw createTurnAbortError();
+            }
+        };
         const activeControllers = this.activeAbortControllers.get(conversationId) ?? new Set();
         activeControllers.add(abortController);
         this.activeAbortControllers.set(conversationId, activeControllers);
+        const activeTurns = this.activeTurns.get(conversationId) ?? new Map();
+        activeTurns.set(abortController, {
+            turnId,
+            openedAt: turnOpenedAt,
+            activeMessageIds: messages.map((message) => message.id).filter(Boolean),
+        });
+        this.activeTurns.set(conversationId, activeTurns);
         const writeTurn = async (state) => {
             if (!runtimeState || !agentId)
                 return;
@@ -947,6 +1062,7 @@ export class CanonAgent {
             })).catch(() => { });
         };
         const setLiveState = async (state, text, streamingStatus) => {
+            throwIfAborted();
             await writeTurn(state);
             if (streamingStatus) {
                 try {
@@ -1007,10 +1123,12 @@ export class CanonAgent {
                 return;
             // Build reply functions
             const replyFinal = async (text, options) => {
+                throwIfAborted();
                 try {
                     await this.apiClient.setTyping(conversationId, true, 'typing');
                 }
                 catch { }
+                throwIfAborted();
                 const sendOptions = withActiveSelfContext(options);
                 const result = await this.apiClient.sendMessage(conversationId, text, {
                     ...sendOptions,
@@ -1029,10 +1147,12 @@ export class CanonAgent {
                 return result;
             };
             const replyProgress = async (text, options) => {
+                throwIfAborted();
                 await setLiveState('streaming', text, 'streaming');
                 if (!options?.durable) {
                     return { turnId, durable: false, messageId: null };
                 }
+                throwIfAborted();
                 const { durable: _durable, ...sendOptions } = options;
                 const sendOptionsWithContext = withActiveSelfContext(sendOptions);
                 const result = await this.apiClient.sendMessage(conversationId, text, {
@@ -1054,6 +1174,9 @@ export class CanonAgent {
                 }
             }
             const latestMessage = hydratedMessages[hydratedMessages.length - 1] ?? null;
+            let replyContext = latestMessage
+                ? resolveCanonReplyContext({ message: latestMessage, messages: history })
+                : null;
             const resolvedActiveSelfContextId = resolveMessageActiveSelfContextId({
                 messageId: latestMessage?.id,
                 activeSelfContextIdByMessageId: page.activeSelfContextIdByMessageId,
@@ -1075,6 +1198,44 @@ export class CanonAgent {
                 inboundPolicy: 'approval-required',
                 groupJoinPolicy: 'approval-required',
             };
+            const provenance = latestMessage
+                ? resolveRuntimeProvenance({
+                    provenance: provenanceByMessageId?.get(latestMessage.id) ?? null,
+                    conversationId,
+                    conversationType: conversation.type,
+                    memberCount: conversation.memberIds.length,
+                    senderId: latestMessage.senderId,
+                    senderName: latestMessage.senderName ?? latestMessage.senderId,
+                    senderType: latestMessage.senderType,
+                    isOwner: latestMessage.isOwner,
+                    agentId: agent.agentId,
+                    mentions: latestMessage.mentions,
+                    activeSelfContextId,
+                    selfContexts,
+                })
+                : resolveRuntimeProvenance({
+                    conversationId,
+                    conversationType: conversation.type,
+                    memberCount: conversation.memberIds.length,
+                    senderId: '',
+                    senderType: 'human',
+                    isOwner: false,
+                    agentId: agent.agentId,
+                    activeSelfContextId,
+                    selfContexts,
+                });
+            if (replyContext?.found && replyContext.attachments?.length) {
+                try {
+                    const materializedReply = await materializeReplyContextMedia(replyContext, {
+                        agentId: agent.agentId,
+                        conversationId,
+                    });
+                    replyContext = materializedReply.replyContext;
+                }
+                catch (error) {
+                    console.error(`[canon-sdk] Failed to materialize reply context media for ${conversationId}:`, error instanceof Error ? error.message : error);
+                }
+            }
             const membershipChange = this.pendingMembershipChanges.get(conversationId) ?? null;
             this.pendingMembershipChanges.delete(conversationId);
             const groupContext = this.buildGroupContext({
@@ -1110,12 +1271,60 @@ export class CanonAgent {
                 ...(options ?? {}),
                 sourceConversationId: conversationId,
             });
+            const requestApproval = async (request) => {
+                throwIfAborted();
+                const manager = this.ensureApprovalManager(agent);
+                if (!manager) {
+                    return { decision: 'deny' };
+                }
+                shouldPersistTurnState = true;
+                try {
+                    try {
+                        await this.apiClient.clearStreaming(conversationId);
+                    }
+                    catch { }
+                    await writeTurn('waiting_input');
+                    try {
+                        await this.apiClient.setTyping(conversationId, false);
+                    }
+                    catch { }
+                    const result = await manager.requestApproval(conversationId, request.toolName, request.toolInput ?? {}, {
+                        riskLevel: request.riskLevel,
+                        risk: request.risk,
+                        category: request.category,
+                        runtimeId: request.runtimeId,
+                        turnId: request.turnId ?? turnId,
+                        native: request.native,
+                        toolSummary: request.toolSummary,
+                        details: request.details,
+                        ignoreSessionRules: request.ignoreSessionRules,
+                        allowSessionRule: request.allowSessionRule,
+                    });
+                    throwIfAborted();
+                    shouldPersistTurnState = false;
+                    try {
+                        await this.apiClient.setTyping(conversationId, true, 'thinking');
+                    }
+                    catch { }
+                    await setLiveState('thinking', 'Thinking...', 'thinking');
+                    return result;
+                }
+                catch (error) {
+                    if (abortController.signal.aborted || isAbortLikeError(error)) {
+                        throw error;
+                    }
+                    shouldPersistTurnState = false;
+                    return { decision: 'deny' };
+                }
+            };
             const uploadFile = (filePath, options) => uploadMediaFile(this.apiClient, conversationId, filePath, options);
             const replyWithFile = async (filePath, text = '', options) => {
+                throwIfAborted();
                 try {
                     await this.apiClient.setTyping(conversationId, true, 'typing');
                 }
                 catch { }
+                throwIfAborted();
                 try {
                     const result = await sendMediaFileMessage(this.apiClient, conversationId, filePath, text, {
                         ...(options?.replyTo ? { replyTo: options.replyTo } : {}),
@@ -1147,9 +1356,11 @@ export class CanonAgent {
                 }
             };
             // Invoke handler
+            throwIfAborted();
             await this.handler({
                 messages: hydratedMessages,
                 history,
+                replyContext,
                 conversationId,
                 conversation,
                 ...(groupContext ? { groupContext } : {}),
@@ -1166,6 +1377,8 @@ export class CanonAgent {
                 agent,
                 activeSelfContextId,
                 selfContexts,
+                provenance,
+                requestApproval,
                 abortSignal: abortController.signal,
                 media: {
                     materialize: (message = hydratedMessages[hydratedMessages.length - 1], options) => {
@@ -1236,6 +1449,10 @@ export class CanonAgent {
             }
         }
         catch (err) {
+            if (abortController.signal.aborted || isAbortLikeError(err)) {
+                await writeTurn('interrupted');
+                return;
+            }
             console.error(`[canon-sdk] Handler error for ${conversationId}:`, err);
             await writeTurn('interrupted');
         }
@@ -1245,6 +1462,11 @@ export class CanonAgent {
             if (activeControllers?.size === 0) {
                 this.activeAbortControllers.delete(conversationId);
             }
+            const activeTurns = this.activeTurns.get(conversationId);
+            activeTurns?.delete(abortController);
+            if (activeTurns?.size === 0) {
+                this.activeTurns.delete(conversationId);
+            }
             clearInterval(thinkingKeepalive);
             // Always clear typing when done
             try {

package/dist/debouncer.d.ts

@@ -1,13 +1,14 @@
-import type { CanonMessage } from '@canonmsg/core';
+import type { CanonMessage, CanonRuntimeProvenance } from '@canonmsg/core';
 export declare class Debouncer {
     private debounceMs;
     private pending;
+    private provenanceByMessageId;
     private timers;
     private orderedFlags;
     private callback;
     constructor(debounceMs: number);
-    setCallback(cb: (conversationId: string, messages: CanonMessage[]) => void): void;
-    add(conversationId: string, message: CanonMessage): void;
+    setCallback(cb: (conversationId: string, messages: CanonMessage[], provenanceByMessageId: ReadonlyMap<string, CanonRuntimeProvenance>) => void): void;
+    add(conversationId: string, message: CanonMessage, provenance?: CanonRuntimeProvenance | null): void;
     private flush;
     destroy(): void;
 }

package/dist/debouncer.js

@@ -1,6 +1,7 @@
 export class Debouncer {
     debounceMs;
     pending = new Map();
+    provenanceByMessageId = new Map();
     timers = new Map();
     // Track whether each conversation's pending messages are already in sorted
     // order so we can skip the sort on flush when possible (#10)
@@ -12,8 +13,11 @@ export class Debouncer {
     setCallback(cb) {
         this.callback = cb;
     }
-    add(conversationId, message) {
+    add(conversationId, message, provenance) {
         const existing = this.pending.get(conversationId) || [];
+        if (provenance) {
+            this.provenanceByMessageId.set(message.id, provenance);
+        }
         // Deduplicate by message ID
         if (!existing.some((m) => m.id === message.id)) {
             if (existing.length === 0) {
@@ -50,7 +54,15 @@ export class Debouncer {
             if (!isOrdered) {
                 messages.sort((a, b) => new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime());
             }
-            this.callback(conversationId, messages);
+            const provenanceByMessageId = new Map();
+            for (const message of messages) {
+                const provenance = this.provenanceByMessageId.get(message.id);
+                if (provenance) {
+                    provenanceByMessageId.set(message.id, provenance);
+                    this.provenanceByMessageId.delete(message.id);
+                }
+            }
+            this.callback(conversationId, messages, provenanceByMessageId);
         }
     }
     destroy() {
@@ -59,6 +71,7 @@ export class Debouncer {
         }
         this.timers.clear();
         this.pending.clear();
+        this.provenanceByMessageId.clear();
         this.orderedFlags.clear();
     }
 }

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 export { CanonAgent } from './canon-agent.js';
 export type { AgentContactsAPI, AgentUsersAPI } from './canon-agent.js';
-export { CanonApiError, HOST_ADMISSION_ACTION_CAPABILITIES, HOST_ADMISSION_ACTIONS_DISABLED, } from '@canonmsg/core';
-export type { CanonContact, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeFact, CanonRuntimeFactGroup, CanonResolveAdmissionResult, ContactAddedPayload, ContactCardPayload, ContactRemovedPayload, ContactSource, HostAdmissionActionCapabilities, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, } from '@canonmsg/core';
+export { ApprovalManager, buildApprovalOutcome, buildApprovalReply, buildApprovalRequest, CanonApiError, DEFAULT_APPROVAL_CONFIG, generateApprovalId, HOST_ADMISSION_ACTION_CAPABILITIES, HOST_ADMISSION_ACTIONS_DISABLED, parseApprovalReplyMetadata, parseApprovalRequestMetadata, parseSessionRule, parseTextApprovalReply, redactSecrets, } from '@canonmsg/core';
+export type { ApprovalConfig, ApprovalNativeRequestMetadata, ApprovalOutcomeMetadata, ApprovalReplyMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalResult, ApprovalRisk, CanonContact, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeFact, CanonRuntimeFactGroup, CanonResolveAdmissionResult, ContactAddedPayload, ContactCardPayload, ContactRemovedPayload, ContactSource, HostAdmissionActionCapabilities, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, SessionRule, } from '@canonmsg/core';
 export { SessionManager } from './session-manager.js';
-export { DEFAULT_MEDIA_CACHE_DIR, getCodexImagePath, getMessageAttachments, inferUploadMimeType, isAnthropicImageAttachment, materializeAttachment, materializeMessageMedia, resolveAttachmentMimeType, sendMediaFileMessage, toAnthropicImageBlock, uploadMediaFile, } from './media.js';
-export type { AnthropicImageBlock, AnthropicImageMimeType, MaterializeMediaOptions, MaterializedCanonAttachment, ReplyWithFileOptions, UploadMediaFileOptions, } from './media.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, CanonSelfContext, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, CreateConversationOptions, } from '@canonmsg/core';
-export type { CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, ContactRequestHandler, MessageHandler, MessageHandlerContext, ProgressMessageOptions, ProgressMessageResult, ReachOutOptions, ReachOutResult, RuntimePrimitiveContext, RuntimePrimitiveHandler, RuntimePrimitiveHandlers, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';
+export type { AgentContext, CanonGroupContext, CanonKnownRecentParticipant, CanonMembershipChange, CanonContactRequest, CanonMessage, CanonConversation, CanonReplyContext, CanonSelfContext, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, CreateConversationOptions, } from '@canonmsg/core';
+export type { CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, ContactRequestHandler, MessageHandler, MessageHandlerContext, ProgressMessageOptions, ProgressMessageResult, ReachOutOptions, ReachOutResult, RuntimeApprovalRequest, RuntimePrimitiveContext, RuntimePrimitiveHandler, RuntimePrimitiveHandlers, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';

package/dist/index.js

@@ -1,4 +1,4 @@
 export { CanonAgent } from './canon-agent.js';
-export { CanonApiError, HOST_ADMISSION_ACTION_CAPABILITIES, HOST_ADMISSION_ACTIONS_DISABLED, } from '@canonmsg/core';
+export { ApprovalManager, buildApprovalOutcome, buildApprovalReply, buildApprovalRequest, CanonApiError, DEFAULT_APPROVAL_CONFIG, generateApprovalId, HOST_ADMISSION_ACTION_CAPABILITIES, HOST_ADMISSION_ACTIONS_DISABLED, parseApprovalReplyMetadata, parseApprovalRequestMetadata, parseSessionRule, parseTextApprovalReply, redactSecrets, } from '@canonmsg/core';
 export { SessionManager } from './session-manager.js';
-export { DEFAULT_MEDIA_CACHE_DIR, getCodexImagePath, getMessageAttachments, inferUploadMimeType, isAnthropicImageAttachment, materializeAttachment, materializeMessageMedia, resolveAttachmentMimeType, sendMediaFileMessage, toAnthropicImageBlock, uploadMediaFile, } from './media.js';
+export { DEFAULT_MEDIA_CACHE_DIR, getCodexImagePath, getMessageAttachments, inferUploadMimeType, isAnthropicImageAttachment, materializeAttachment, materializeMessageMedia, materializeReplyContextMedia, resolveAttachmentMimeType, sendMediaFileMessage, toAnthropicImageBlock, uploadMediaFile, } from './media.js';

package/dist/media.d.ts

@@ -1,4 +1,4 @@
-import { CanonClient, type CanonMessage, type MediaAttachment, type SendMessageOptions } from '@canonmsg/core';
+import { CanonClient, type CanonReplyContext, type CanonMessage, type MediaAttachment, type SendMessageOptions } from '@canonmsg/core';
 export interface MaterializeMediaOptions {
     agentId: string;
     conversationId: string;
@@ -21,6 +21,10 @@ export interface MaterializedCanonAttachment extends MediaAttachment {
     conversationId: string;
     messageId: string;
 }
+export interface MaterializedCanonReplyContext {
+    replyContext: CanonReplyContext | null;
+    materialized: MaterializedCanonAttachment[];
+}
 /**
  * Anthropic `image` content blocks only accept these MIME types for
  * base64 sources. Anything outside this set must either be re-encoded or
@@ -46,6 +50,7 @@ export declare function materializeAttachment(attachment: MediaAttachment, optio
     index?: number;
 }): Promise<MaterializedCanonAttachment>;
 export declare function materializeMessageMedia(message: Pick<CanonMessage, 'id' | 'attachments'>, options: Omit<MaterializeMediaOptions, 'messageId'>): Promise<MaterializedCanonAttachment[]>;
+export declare function materializeReplyContextMedia(replyContext: CanonReplyContext | null, options: Omit<MaterializeMediaOptions, 'messageId'>): Promise<MaterializedCanonReplyContext>;
 export declare function inferUploadMimeType(filePath: string, overrideMimeType?: string): string;
 export declare function uploadMediaFile(client: CanonClient, conversationId: string, filePath: string, options?: UploadMediaFileOptions): Promise<{
     url: string;

package/dist/media.js

@@ -1,6 +1,6 @@
 import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
 import { basename, dirname, extname, join } from 'node:path';
-import { CANON_DIR, } from '@canonmsg/core';
+import { CANON_DIR, renderCanonHostInboundContent, } from '@canonmsg/core';
 const ANTHROPIC_IMAGE_MIME_TYPES = new Set([
     'image/jpeg',
     'image/png',
@@ -141,6 +141,31 @@ export async function materializeMessageMedia(message, options) {
         index,
     })));
 }
+export async function materializeReplyContextMedia(replyContext, options) {
+    if (!replyContext?.found || !replyContext.attachments?.length) {
+        return { replyContext, materialized: [] };
+    }
+    const materialized = (await Promise.all(replyContext.attachments.map((attachment, index) => attachment.url
+        ? materializeAttachment(attachment, {
+            ...options,
+            messageId: replyContext.messageId,
+            index,
+        })
+        : Promise.resolve(null)))).filter((attachment) => attachment !== null);
+    return {
+        replyContext: {
+            ...replyContext,
+            body: renderCanonHostInboundContent({
+                text: replyContext.text,
+                contentType: replyContext.contentType,
+                attachments: replyContext.attachments,
+                contactCard: replyContext.contactCard,
+                senderType: replyContext.senderType ?? undefined,
+            }, materialized),
+        },
+        materialized,
+    };
+}
 export function inferUploadMimeType(filePath, overrideMimeType) {
     if (overrideMimeType)
         return overrideMimeType;

package/dist/realtime.js

@@ -52,7 +52,7 @@ export class RealtimeManager {
                         ...(m.contactCard ? { contactCard: m.contactCard } : {}),
                         ...(m.metadata ? { metadata: m.metadata } : {}),
                     };
-                    this.debouncer.add(payload.conversationId, message);
+                    this.debouncer.add(payload.conversationId, message, payload.provenance ?? null);
                 },
                 onAgentContext: (ctx) => {
                     this.onAgentContext?.(ctx);

package/dist/types.d.ts

@@ -1,5 +1,5 @@
-export type { AddMemberResult, AgentClientType, CanonGroupContext, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeDescriptor, CanonRuntimeFact, CanonRuntimeFactGroup, CanonRuntimePrimitiveId, CanonMessage, CanonConversation, CanonContact, CanonContactRequest, CanonResolveAdmissionResult, ContactAddedPayload, ContactRemovedPayload, ContactSource, AgentContext, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonSelfContext, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, SessionConfig, CreateConversationOptions, TurnLifecycleState, } from '@canonmsg/core';
-import type { AddMemberResult, CanonGroupContext, CanonMessage, CanonConversation, ContactCardPayload, CanonRuntimeActionDispatch, CanonRuntimePrimitiveId, SendMessageOptions, SendContextualSelfContextInput, SessionConfig } from '@canonmsg/core';
+export type { AddMemberResult, AgentClientType, CanonGroupContext, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeDescriptor, CanonRuntimeFact, CanonRuntimeFactGroup, CanonRuntimePrimitiveId, CanonRuntimeProvenance, CanonMessage, CanonConversation, CanonReplyContext, CanonContact, CanonContactRequest, CanonResolveAdmissionResult, ContactAddedPayload, ContactRemovedPayload, ContactSource, AgentContext, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonSelfContext, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, SessionConfig, CreateConversationOptions, TurnLifecycleState, ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalRisk, ApprovalReplyMetadata, ApprovalOutcomeMetadata, SessionRule, ApprovalResult, } from '@canonmsg/core';
+import type { AddMemberResult, CanonGroupContext, CanonMessage, CanonConversation, CanonReplyContext, ContactCardPayload, CanonRuntimeActionDispatch, CanonRuntimePrimitiveId, CanonRuntimeProvenance, ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalResult, ApprovalRisk, SendMessageOptions, SendContextualSelfContextInput, SessionConfig } from '@canonmsg/core';
 import type { MaterializeMediaOptions, MaterializedCanonAttachment, ReplyWithFileOptions, UploadMediaFileOptions } from './media.js';
 export interface ProgressMessageOptions extends SendMessageOptions {
     /**
@@ -34,9 +34,33 @@ export interface TurnController {
     setTool: (text: string) => Promise<void>;
     setWaitingInput: (text?: string) => Promise<void>;
 }
+export interface RuntimeApprovalRequest {
+    /** Native runtime/tool/action name that is asking for permission. */
+    toolName: string;
+    /** Structured native input. Raw values are summarized/redacted before storage. */
+    toolInput?: Record<string, unknown>;
+    /** Optional pre-redacted summary when a runtime already has user-facing copy. */
+    toolSummary?: string;
+    category?: ApprovalRequestCategory;
+    risk?: ApprovalRisk;
+    riskLevel?: 'normal' | 'destructive';
+    runtimeId?: string;
+    turnId?: string;
+    native?: ApprovalNativeRequestMetadata;
+    details?: ApprovalRequestDetail[];
+    /**
+     * Ignore in-memory session rules for this approval request. Useful when the
+     * action was triggered by someone other than the agent owner.
+     */
+    ignoreSessionRules?: boolean;
+    /** Whether an approval reply may set an in-memory session rule. */
+    allowSessionRule?: boolean;
+}
 export interface MessageHandlerContext {
     messages: CanonMessage[];
     history: CanonMessage[];
+    /** Resolved message/media content for the latest swipe-reply target, if any. */
+    replyContext: CanonReplyContext | null;
     conversationId: string;
     conversation: CanonConversation;
     /** Lightweight group awareness, present for group conversations. */
@@ -77,6 +101,14 @@ export interface MessageHandlerContext {
     activeSelfContextId: string | null;
     /** Canon-provided private context explaining this agent's cross-session actions. */
     selfContexts?: import('@canonmsg/core').CanonSelfContext[];
+    /** Trusted Canon provenance for the latest inbound message in this handler batch. */
+    provenance: CanonRuntimeProvenance;
+    /**
+     * Ask the conversation owner to approve a native runtime action. This only
+     * renders Canon's inline approval card; runtimes must explicitly wait for
+     * and enforce the returned decision in their own approval hook.
+     */
+    requestApproval: (request: RuntimeApprovalRequest) => Promise<ApprovalResult>;
     /** Canon-managed local media access for the current conversation. */
     media: {
         materialize: (message?: CanonMessage, options?: Omit<MaterializeMediaOptions, 'agentId' | 'conversationId' | 'messageId'>) => Promise<MaterializedCanonAttachment[]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-sdk",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "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": "^0.18.0"
+    "@canonmsg/core": "^0.19.0"
   },
   "publishConfig": {
     "access": "public"