@canonmsg/agent-sdk 9.0.0 → 10.0.0

package/README.md

@@ -190,7 +190,7 @@ The `message` event handler receives a context object with:
 | `leave` | `() => Promise<void>` | Leave the current group conversation |
 | `react` | `(messageId, emoji) => Promise<void>` | Toggle an emoji reaction |
 | `addMember` / `removeMember` | functions | Manage group members when the agent has permission |
-| `communicate` | function | Message an existing conversation, start a direct conversation, create a group, or forward an exact message |
+| `communicate` | function | Message an existing conversation, start a direct conversation, create a group, forward an exact message, share a contact, or manage group members |
 | `agent` | `AgentContext` | Trusted Canon agent identity and access context |
 | `activeSelfContextId` | `string \| null` | Active private self-context id for this turn |
 | `selfContexts` | `CanonSelfContext[] \| undefined` | Private context explaining this agent's cross-session actions |
@@ -200,6 +200,7 @@ The `message` event handler receives a context object with:
 | `turnVerbosity` | `'verbose' \| 'quiet'` | Resolved emission mode for this turn — see [Turn verbosity](#turn-verbosity). Fixed for the whole turn |
 | `requestApproval` | `(request) => Promise<ApprovalResult>` | Render a Canon approval card and wait for the decision. Fail-closed: returns `{ decision: 'deny' }` on any non-abort failure instead of throwing |
 | `requestRuntimeInput` | `(request) => Promise<RuntimeInputResult>` | Render a Canon input card for clarification, sudo, or secret values |
+| `requestPlanReview` | `(request) => Promise<RuntimePlanReviewResult>` | Render Canon's native plan-review card and wait for approve, revise, reject, cancellation, or timeout |
 | `requestCard` / `sendCard` | functions | Render a generic `canon.card.v1` rich card. `requestCard` blocks only on cards that carry an `actions` block; `sendCard` posts a display card |
 | `media` | `{ materialize, uploadFile, replyWithFile }` | Canon-managed access to real media bytes via `~/.canon/media-cache` plus local-file uploads back into Canon |
 | `session` | `SessionInfo \| undefined` | Per-conversation queue/session state when sessions are enabled |
@@ -212,16 +213,15 @@ Messages from the agent itself are automatically filtered out -- your handler on
 
 ## Events
 
-`agent.on(event, handler)` accepts eleven events. Each event holds a single handler; registering again replaces it.
+`agent.on(event, handler)` accepts ten events. Each event holds a single handler; registering again replaces it.
 
 | Event | Payload | Notes |
 |---|---|---|
 | `message` | `MessageHandlerContext` | Debounced inbound batch for one conversation |
 | `messageUpdated` | `MessageUpdatedPayload` | Reaction/status changes; not a new turn |
-| `contactRequest` | `CanonContactRequest` | Awareness only — the owner still approves |
-| `contactApproved` | `CanonContactRequest` | Awareness only |
 | `contactAdded` | `ContactAddedPayload` | A contact edge now exists |
 | `contactRemoved` | `ContactRemovedPayload` | A contact edge was removed |
+| `participationSuppressed` | `ParticipationSuppressedPayload` | Observe-only notice that policy withheld a turn |
 | `interrupt` | `RuntimeSignalContext` | Same signal as `runtimeControls.onInterrupt` |
 | `stopAndDrop` | `RuntimeSignalContext` | Same signal as `runtimeControls.onStopAndDrop` |
 | `newSession` | `RuntimeSignalContext` | Same signal as `runtimeControls.onNewSession` |
@@ -246,7 +246,7 @@ Reaction update events are interaction state, not new chat turns. They do not ca
 
 ### Human-in-the-loop cards
 
-Use `ctx.requestRuntimeInput(...)` when the runtime needs clarification, a sudo value, or a secret value from the user. Use `ctx.requestApproval(...)` when the runtime needs an allow/deny decision before taking an action. Canon creates the visible card, routes the user's response, and returns the result to the handler; your runtime remains responsible for enforcing that result.
+Use `ctx.requestRuntimeInput(...)` when the runtime needs clarification, a sudo value, or a secret value from the user. Use `ctx.requestPlanReview(...)` when a planning runtime needs Canon's native approve/revise/reject card, and `ctx.requestApproval(...)` when the runtime needs an allow/deny decision before taking an action. Canon creates the visible card, routes the user's response, and returns the result to the handler; your runtime remains responsible for enforcing that result.
 
 `requestApproval` is fail-closed and never throws: it returns `{ decision: 'deny' }` when no approval manager can be built (no resolved agent identity or owner) and on any non-abort error. A `deny` therefore does not prove a human said no — check your own preconditions before treating it as a decision.
 
@@ -277,22 +277,6 @@ const review = await ctx.requestCard({
 
 The SDK does not validate card documents — it forwards `request.card` to Canon as-is, and a malformed card surfaces as a backend 400. Install [`@canonmsg/rich-cards`](https://www.npmjs.com/package/@canonmsg/rich-cards) if you want strict authoring validation (`validateCard`, the `card()` builder, and the `canon-card` CLI); it is a separate package and not a dependency of this one.
 
-## Contact Request Awareness
-
-Agents can also observe contact-request lifecycle events without becoming the approver:
-
-```typescript
-agent.on('contactRequest', (request) => {
-  console.log('New request aimed at this agent:', request.requesterName);
-});
-
-agent.on('contactApproved', (request) => {
-  console.log('Request approved:', request.id);
-});
-```
-
-These are awareness callbacks only. Canon still routes approval and rejection for agent-targeted requests through the human owner's UI/callable flow.
-
 ### Turn-aware example
 
 ```typescript

package/dist/canon-agent.d.ts

@@ -1,5 +1,5 @@
 import { type AddMemberResult, type CanonContact, type CommunicateInput, type CommunicateResult, type CanonConversation, type CanonConversationsPage, type CanonConversationsPageOptions, type CreateGroupOptions, type CreateGroupResult, type CanonRuntimeActivityItem, type CanonRuntimeCommandDescriptor, type CanonRuntimeFact, type CanonRuntimePrimitiveId, type ClearRuntimeActivityOptions, type CanonVoiceSession, type CanonVoiceSessionToken, type CreateVoiceSessionOptions, type VoiceSessionEventPayload } from '@canonmsg/core';
-import type { CanonAgentConnectionOptions, CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, MessageHandler, MessageUpdatedHandler, ParticipationSuppressedHandler, ContactRequestHandler, RuntimeSignalHandler, RuntimePrimitiveHandler } from './types.js';
+import type { CanonAgentConnectionOptions, CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, MessageHandler, MessageUpdatedHandler, ParticipationSuppressedHandler, RuntimeSignalHandler, RuntimePrimitiveHandler } from './types.js';
 /**
  * Contact-graph operations exposed under `agent.contacts`. Wraps the REST
  * endpoints in CanonClient — the same surface a human user would hit through
@@ -40,8 +40,6 @@ export declare class CanonAgent {
     private realtimeManager;
     private sessionManager;
     private handler;
-    private contactRequestHandler;
-    private contactApprovedHandler;
     private contactAddedHandler;
     private contactRemovedHandler;
     private messageUpdatedHandler;
@@ -101,8 +99,6 @@ export declare class CanonAgent {
     private filterApprovalReplyMessages;
     on(event: 'message', handler: MessageHandler): void;
     on(event: 'messageUpdated', handler: MessageUpdatedHandler): void;
-    on(event: 'contactRequest', handler: ContactRequestHandler): void;
-    on(event: 'contactApproved', handler: ContactRequestHandler): void;
     on(event: 'contactAdded', handler: ContactAddedHandler): void;
     on(event: 'contactRemoved', handler: ContactRemovedHandler): void;
     /**
@@ -151,12 +147,11 @@ export declare class CanonAgent {
      * Outcome depends on the target's `groupJoinPolicy` and the relationship
      * graph:
      * - `{ status: 'added' }` — the member was added immediately.
-     * - `{ status: 'pending', requestId, requirements }` — the target needs
-     *   policy approval, owner session setup, or both. The server created one
-     *   `group_invite`; membership activates after every requirement is met
-     *   (you can listen for `contact.approved` SSE events to know when).
+     * - `{ status: 'pending', requestId }` — the target needs policy approval.
+     *   The server created one `group_invite`; membership activates after approval
+     *   The approved membership arrives through the normal conversation update.
      *
-     * Throws `CanonApiError` for hard failures (block, inactive, owner-only,
+     * Throws `CanonApiError` for hard failures (block, inactive, closed policy,
      * member cap, requester not authorized).
      */
     addMember(conversationId: string, userId: string): Promise<AddMemberResult>;
@@ -165,7 +160,6 @@ export declare class CanonAgent {
         url: string;
         attachment: import('@canonmsg/core').MediaAttachment;
     }>;
-    private handleContactRequestEvent;
     private handleContactGraphEvent;
     private handleParticipationSuppressedEvent;
     private handleMessageUpdatedEvent;

package/dist/canon-agent.js

@@ -245,6 +245,33 @@ function isAbortLikeError(error) {
         return true;
     return typeof record.message === 'string' && /\babort(?:ed)?\b/i.test(record.message);
 }
+function linkAbortSignals(turnSignal, requestSignal) {
+    if (!requestSignal || requestSignal === turnSignal) {
+        return { signal: turnSignal, dispose: () => { } };
+    }
+    const controller = new AbortController();
+    const abortFrom = (source) => {
+        if (!controller.signal.aborted)
+            controller.abort(source.reason);
+    };
+    const onTurnAbort = () => abortFrom(turnSignal);
+    const onRequestAbort = () => abortFrom(requestSignal);
+    if (turnSignal.aborted)
+        abortFrom(turnSignal);
+    else
+        turnSignal.addEventListener('abort', onTurnAbort, { once: true });
+    if (requestSignal.aborted)
+        abortFrom(requestSignal);
+    else
+        requestSignal.addEventListener('abort', onRequestAbort, { once: true });
+    return {
+        signal: controller.signal,
+        dispose: () => {
+            turnSignal.removeEventListener('abort', onTurnAbort);
+            requestSignal.removeEventListener('abort', onRequestAbort);
+        },
+    };
+}
 export class CanonAgent {
     options;
     runtimeConnection;
@@ -254,8 +281,6 @@ export class CanonAgent {
     realtimeManager = null;
     sessionManager = null;
     handler = null;
-    contactRequestHandler = null;
-    contactApprovedHandler = null;
     contactAddedHandler = null;
     contactRemovedHandler = null;
     messageUpdatedHandler = null;
@@ -457,14 +482,6 @@ export class CanonAgent {
             this.messageUpdatedHandler = handler;
             return;
         }
-        if (event === 'contactRequest') {
-            this.contactRequestHandler = handler;
-            return;
-        }
-        if (event === 'contactApproved') {
-            this.contactApprovedHandler = handler;
-            return;
-        }
         if (event === 'contactAdded') {
             this.contactAddedHandler = handler;
             return;
@@ -607,7 +624,6 @@ export class CanonAgent {
             const runtimeState = this.createRuntimeStatePublisher();
             for (const id of this.cachedConversationIds) {
                 runtimeState?.writeSessionState(id, {
-                    cwd: process.cwd(),
                     isActive: true,
                     ...(this.options.clientType ? { clientType: this.options.clientType } : {}),
                 }).catch(() => { });
@@ -640,14 +656,6 @@ export class CanonAgent {
             this.agentContext = ctx;
             this.ensureApprovalManager(ctx);
         });
-        rtm.setContactRequestHandlers({
-            onContactRequest: (request) => {
-                void this.handleContactRequestEvent(this.contactRequestHandler, request);
-            },
-            onContactApproved: (request) => {
-                void this.handleContactRequestEvent(this.contactApprovedHandler, request);
-            },
-        });
         rtm.setContactGraphHandlers({
             onContactAdded: (payload) => {
                 void this.handleContactGraphEvent(this.contactAddedHandler, payload);
@@ -726,12 +734,11 @@ export class CanonAgent {
      * Outcome depends on the target's `groupJoinPolicy` and the relationship
      * graph:
      * - `{ status: 'added' }` — the member was added immediately.
-     * - `{ status: 'pending', requestId, requirements }` — the target needs
-     *   policy approval, owner session setup, or both. The server created one
-     *   `group_invite`; membership activates after every requirement is met
-     *   (you can listen for `contact.approved` SSE events to know when).
+     * - `{ status: 'pending', requestId }` — the target needs policy approval.
+     *   The server created one `group_invite`; membership activates after approval
+     *   The approved membership arrives through the normal conversation update.
      *
-     * Throws `CanonApiError` for hard failures (block, inactive, owner-only,
+     * Throws `CanonApiError` for hard failures (block, inactive, closed policy,
      * member cap, requester not authorized).
      */
     async addMember(conversationId, userId) {
@@ -743,16 +750,6 @@ export class CanonAgent {
     async uploadMedia(conversationId, data, mimeType, fileName) {
         return this.apiClient.uploadMedia(conversationId, data, mimeType, fileName);
     }
-    async handleContactRequestEvent(handler, request) {
-        if (!handler)
-            return;
-        try {
-            await handler(request);
-        }
-        catch (error) {
-            console.error('[canon-sdk] Contact-request handler failed:', error instanceof Error ? error.message : error);
-        }
-    }
     async handleContactGraphEvent(handler, payload) {
         if (!handler)
             return;
@@ -1219,6 +1216,7 @@ export class CanonAgent {
         // The freshest message in the batch is the turn's trigger — same convention
         // as the provenance lookup for turn verbosity below.
         const triggeringMessageId = messages[messages.length - 1]?.id;
+        const triggeringReplyAuthority = messages[messages.length - 1]?.replyAuthority;
         const agentId = this.agentId;
         const runtimeState = this.createRuntimeStatePublisher();
         const queueDepth = () => this.sessionManager?.getQueueDepth(conversationId) ?? 0;
@@ -1493,9 +1491,12 @@ export class CanonAgent {
             const activeSelfContextId = selfContexts.length > 0 ? resolvedActiveSelfContextId : null;
             const withActiveSelfContext = (options) => {
                 const base = { ...(options ?? {}) };
-                if (base.selfContextId !== undefined)
-                    return base;
-                return activeSelfContextId ? { ...base, selfContextId: activeSelfContextId } : base;
+                const withContext = base.selfContextId !== undefined || !activeSelfContextId
+                    ? base
+                    : { ...base, selfContextId: activeSelfContextId };
+                return withContext.replyAuthority !== undefined || !triggeringReplyAuthority
+                    ? withContext
+                    : { ...withContext, replyAuthority: triggeringReplyAuthority };
             };
             // Core's chunked sender walks the parts in a plain loop and knows nothing
             // about this turn's abort signal, so a stop landing after part 1 would
@@ -1706,6 +1707,7 @@ export class CanonAgent {
             };
             const requestRuntimeInput = async (request) => {
                 throwIfAborted();
+                const linkedSignal = linkAbortSignals(abortController.signal, request.signal);
                 const inputId = safeRuntimeInputId(request.inputId, request.kind);
                 const timeoutMs = Math.max(1_000, request.timeoutMs ?? DEFAULT_RUNTIME_INPUT_TIMEOUT_MS);
                 const expiresAtMs = Date.now() + timeoutMs;
@@ -1761,7 +1763,7 @@ export class CanonAgent {
                     result = await this.ensureRuntimeRequestManager().request('input', conversationId, { kind: request.kind }, {
                         requestId: inputId,
                         expiresAt: expiresAtMs,
-                        signal: abortController.signal,
+                        signal: linkedSignal.signal,
                     });
                     const outcome = buildRuntimeInputOutcome(inputId, result.status, {
                         kind: request.kind,
@@ -1787,7 +1789,7 @@ export class CanonAgent {
                     return result;
                 }
                 catch (error) {
-                    if (abortController.signal.aborted || isAbortLikeError(error)) {
+                    if (abortController.signal.aborted || request.signal?.aborted || isAbortLikeError(error)) {
                         if (requestCreated) {
                             // Abort landing before the manager wired its cancel (e.g. during
                             // the pre-request writeTurn/typing round-trips) leaves the
@@ -1810,6 +1812,81 @@ export class CanonAgent {
                     await resumeTurnFromWaiting();
                     return result;
                 }
+                finally {
+                    linkedSignal.dispose();
+                }
+            };
+            const requestPlanReview = async (request) => {
+                throwIfAborted();
+                const linkedSignal = linkAbortSignals(abortController.signal, request.signal);
+                const planId = request.planId && RUNTIME_INPUT_ID_PATTERN.test(request.planId)
+                    ? request.planId
+                    : randomUUID();
+                const timeoutMs = Math.max(1_000, request.timeoutMs ?? DEFAULT_RUNTIME_INPUT_TIMEOUT_MS);
+                const expiresAtMs = Date.now() + timeoutMs;
+                const responseUserId = normalizeResponseUserId(request.responseUserId)
+                    ?? triggeringHumanId
+                    ?? normalizeResponseUserId(agent.ownerId);
+                let created = false;
+                let result = { status: 'timeout', planId };
+                shouldPersistTurnState = true;
+                try {
+                    result = await this.ensureRuntimeRequestManager().request('plan', conversationId, {
+                        ...(request.title ? { title: request.title } : {}),
+                        ...(request.summary ? { summary: request.summary } : {}),
+                        ...(request.body ? { body: request.body } : {}),
+                        ...(request.allowedPrompts ? { allowedPrompts: request.allowedPrompts } : {}),
+                        ...(responseUserId ? { responseUserId } : {}),
+                        turnId: request.turnId ?? turnId,
+                    }, {
+                        requestId: planId,
+                        expiresAt: expiresAtMs,
+                        responderPolicy: 'infer',
+                        signal: linkedSignal.signal,
+                        onCreated: async () => {
+                            created = true;
+                            try {
+                                await turnOutput.addBlock({
+                                    id: `plan:${planId}`,
+                                    kind: 'input',
+                                    status: 'pending',
+                                    title: request.title ?? 'Plan review',
+                                    summary: request.summary ?? 'Review requested',
+                                });
+                                await turnOutput.waitingInput();
+                            }
+                            catch { }
+                            await writeTurn('waiting_input');
+                            try {
+                                await this.typingSignals.clear(conversationId);
+                            }
+                            catch { }
+                        },
+                    });
+                    throwIfAborted();
+                    shouldPersistTurnState = false;
+                    try {
+                        await turnOutput.completeBlock(`plan:${planId}`, {
+                            summary: `Plan ${result.status}`,
+                        });
+                    }
+                    catch { }
+                    await resumeTurnFromWaiting();
+                    return result;
+                }
+                catch (error) {
+                    if (abortController.signal.aborted || request.signal?.aborted || isAbortLikeError(error)) {
+                        throw error;
+                    }
+                    shouldPersistTurnState = false;
+                    if (!created)
+                        throw error;
+                    await resumeTurnFromWaiting();
+                    return result;
+                }
+                finally {
+                    linkedSignal.dispose();
+                }
             };
             const sendCard = async (request) => {
                 throwIfAborted();
@@ -2020,6 +2097,7 @@ export class CanonAgent {
                 turnVerbosity,
                 requestApproval,
                 requestRuntimeInput,
+                requestPlanReview,
                 requestCard,
                 sendCard,
                 abortSignal: abortController.signal,

package/dist/index.d.ts

@@ -1,11 +1,11 @@
 export { CanonAgent } 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, ParticipationSuppressedPayload, ResolveAdmissionTargetInput, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, ResumableMediaUploadResult, MediaAttachment, VideoProcessingStatus, VideoProcessingErrorCode, RuntimeInputAnswers, RuntimeInputChoice, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, SessionRule, } 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, ParticipationSuppressedPayload, ResolveAdmissionTargetInput, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, ResumableMediaUploadResult, MediaAttachment, VideoProcessingStatus, VideoProcessingErrorCode, RuntimeInputAnswers, RuntimeInputChoice, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, RuntimePlanRequestPayload, RuntimePlanRequestResult, SessionRule, } 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 type { AnthropicImageBlock, AnthropicImageBudgetOptions, AnthropicImageMimeType, MaterializeMediaOptions, MaterializedCanonAttachment, MaterializedCanonReplyContext, ReplyWithFileOptions, UploadMediaFileOptions, } from './media.js';
 export type { SessionConfig, Session } from './session-manager.js';
 export type { CanonAgentTurnVerbosityOption } from './turn-verbosity-option.js';
-export type { AgentContext, CanonGroupContext, CanonKnownRecentParticipant, CanonMembershipChange, CanonContactRequest, GroupInviteRequirements, 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, ContactRequestHandler, FinalMessageResult, MessageHandler, MessageHandlerContext, MessageUpdatedHandler, ParticipationSuppressedHandler, ProgressMessageOptions, ProgressMessageResult, RuntimeApprovalRequest, RuntimeInputRequest, RuntimeInputResult, RuntimeControlSurface, RuntimePrimitiveContext, RuntimePrimitiveHandler, RuntimePrimitiveHandlers, SessionInfo, SessionOptions, DeliveryMode, } from './types.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';

package/dist/realtime.d.ts

@@ -1,4 +1,4 @@
-import { type AgentContext, type ContactAddedPayload, type ContactApprovedPayload, type ContactRemovedPayload, type ContactRequestPayload, type ConversationUpdatedPayload, type MessageUpdatedPayload, type ParticipationSuppressedPayload, type VoiceSessionEventPayload } from '@canonmsg/core';
+import { type AgentContext, type ContactAddedPayload, type ContactRemovedPayload, type ConversationUpdatedPayload, type MessageUpdatedPayload, type ParticipationSuppressedPayload, type VoiceSessionEventPayload } from '@canonmsg/core';
 import { Debouncer } from './debouncer.js';
 /**
  * Wraps @canonmsg/core's CanonStream with SDK-specific features:
@@ -15,8 +15,6 @@ export declare class RealtimeManager {
     private lastSseErrorAt;
     private suppressedSseErrorCount;
     private onAgentContext;
-    private onContactRequest;
-    private onContactApproved;
     private onContactAdded;
     private onContactRemoved;
     private onConversationUpdated;
@@ -35,10 +33,6 @@ export declare class RealtimeManager {
     private pruneRecentInboundMessageIds;
     private logSseError;
     setOnAgentContext(cb: (ctx: AgentContext) => void): void;
-    setContactRequestHandlers(handlers: {
-        onContactRequest?: (payload: ContactRequestPayload) => void;
-        onContactApproved?: (payload: ContactApprovedPayload) => void;
-    }): void;
     setContactGraphHandlers(handlers: {
         onContactAdded?: (payload: ContactAddedPayload) => void;
         onContactRemoved?: (payload: ContactRemovedPayload) => void;

package/dist/realtime.js

@@ -16,8 +16,6 @@ export class RealtimeManager {
     lastSseErrorAt = 0;
     suppressedSseErrorCount = 0;
     onAgentContext = null;
-    onContactRequest = null;
-    onContactApproved = null;
     onContactAdded = null;
     onContactRemoved = null;
     onConversationUpdated = null;
@@ -86,6 +84,7 @@ export class RealtimeManager {
                         createdAt: m.createdAt ?? new Date().toISOString(),
                         ...(m.contactCard ? { contactCard: m.contactCard } : {}),
                         ...(m.metadata ? { metadata: m.metadata } : {}),
+                        ...(payload.replyAuthority ? { replyAuthority: payload.replyAuthority } : {}),
                     };
                     this.debouncer.add(payload.conversationId, message, payload.provenance ?? null);
                 },
@@ -99,12 +98,6 @@ export class RealtimeManager {
                 onAgentContext: (ctx) => {
                     this.onAgentContext?.(ctx);
                 },
-                onContactRequest: (payload) => {
-                    this.onContactRequest?.(payload);
-                },
-                onContactApproved: (payload) => {
-                    this.onContactApproved?.(payload);
-                },
                 onContactAdded: (payload) => {
                     this.onContactAdded?.(payload);
                 },
@@ -173,10 +166,6 @@ export class RealtimeManager {
     setOnAgentContext(cb) {
         this.onAgentContext = cb;
     }
-    setContactRequestHandlers(handlers) {
-        this.onContactRequest = handlers.onContactRequest ?? null;
-        this.onContactApproved = handlers.onContactApproved ?? null;
-    }
     setContactGraphHandlers(handlers) {
         this.onContactAdded = handlers.onContactAdded ?? null;
         this.onContactRemoved = handlers.onContactRemoved ?? null;

package/dist/types.d.ts

@@ -1,5 +1,5 @@
-export type { AddMemberResult, GroupInviteRequirements, AgentClientType, CanonGroupContext, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeDescriptor, CanonRuntimeFact, CanonRuntimeFactGroup, CanonRuntimePrimitiveId, CanonRuntimeProvenance, CanonTurnContextV2, CanonMessage, CanonConversation, CommunicateInput, CommunicateResult, CanonReplyContext, CanonContact, CanonContactRequest, CanonResolveAdmissionResult, ContactAddedPayload, ContactRemovedPayload, ContactSource, AgentContext, ResolveAdmissionTargetInput, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonSelfContext, CreateGroupOptions, CreateGroupResult, SendMessageOptions, SessionConfig, TurnLifecycleState, TurnOutputBlock, TurnOutputBlockInput, ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalRisk, ApprovalReplyMetadata, ApprovalOutcomeMetadata, RuntimeInputChoice, RuntimeInputAnswers, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, RuntimeCardNativeMetadata, RuntimeCardV1, ResumableMediaUploadResult, MediaAttachment, VideoProcessingStatus, VideoProcessingErrorCode, SessionRule, ApprovalResult, } from '@canonmsg/core';
-import type { AddMemberResult, CanonGroupContext, CanonMessage, CanonConversation, CommunicateInput, CommunicateResult, CanonReplyContext, CanonRuntimeActionDispatch, CanonRuntimePrimitiveId, CanonRuntimeProvenance, CanonTurnContextV2, ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalResult, ApprovalRisk, RuntimeInputChoice, RuntimeInputAnswers, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, RuntimeCardNativeMetadata, RuntimeCardV1, ResumableMediaUploadResult, SendMessageOptions, TurnOutputBlock, TurnOutputBlockInput } from '@canonmsg/core';
+export type { AddMemberResult, AgentClientType, CanonGroupContext, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeDescriptor, CanonRuntimeFact, CanonRuntimeFactGroup, CanonRuntimePrimitiveId, CanonRuntimeProvenance, CanonTurnContextV2, CanonMessage, CanonConversation, CommunicateInput, CommunicateResult, CanonReplyContext, CanonContact, CanonResolveAdmissionResult, ContactAddedPayload, ContactRemovedPayload, ContactSource, AgentContext, ResolveAdmissionTargetInput, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonSelfContext, CreateGroupOptions, CreateGroupResult, SendMessageOptions, TurnLifecycleState, TurnOutputBlock, TurnOutputBlockInput, ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalRisk, ApprovalReplyMetadata, ApprovalOutcomeMetadata, RuntimeInputChoice, RuntimeInputAnswers, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, RuntimePlanRequestPayload, RuntimePlanRequestResult, RuntimeCardNativeMetadata, RuntimeCardV1, ResumableMediaUploadResult, MediaAttachment, VideoProcessingStatus, VideoProcessingErrorCode, SessionRule, ApprovalResult, } from '@canonmsg/core';
+import type { AddMemberResult, CanonGroupContext, CanonMessage, CanonConversation, CommunicateInput, CommunicateResult, CanonReplyContext, CanonRuntimeActionDispatch, CanonRuntimePrimitiveId, CanonRuntimeProvenance, CanonTurnContextV2, ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalResult, ApprovalRisk, RuntimeInputChoice, RuntimeInputAnswers, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, RuntimePlanRequestPayload, RuntimePlanRequestResult, RuntimeCardNativeMetadata, RuntimeCardV1, ResumableMediaUploadResult, SendMessageOptions, TurnOutputBlock, TurnOutputBlockInput } from '@canonmsg/core';
 import type { MaterializeMediaOptions, MaterializedCanonAttachment, ReplyWithFileOptions, UploadMediaFileOptions } from './media.js';
 export interface ProgressMessageOptions extends SendMessageOptions {
     /**
@@ -119,6 +119,8 @@ export interface RuntimeInputRequest {
     native?: RuntimeInputNativeMetadata;
     inputId?: string;
     timeoutMs?: number;
+    /** Aborts the pending input request without waiting for the enclosing turn to stop. */
+    signal?: AbortSignal;
     /** Human conversation member who should answer. Secret and sudo prompts remain owner-only. */
     responseUserId?: string;
 }
@@ -128,6 +130,14 @@ export interface RuntimeInputResult {
     answers?: RuntimeInputAnswers;
     inputId: string;
 }
+/** Native Canon plan-review card backed by Core's existing runtime-plan interaction. */
+export interface RuntimePlanReviewRequest extends RuntimePlanRequestPayload {
+    planId?: string;
+    timeoutMs?: number;
+    /** Aborts the pending plan review without waiting for the enclosing turn to stop. */
+    signal?: AbortSignal;
+}
+export type RuntimePlanReviewResult = RuntimePlanRequestResult;
 export interface RuntimeCardRequest {
     card: RuntimeCardV1;
     cardId?: string;
@@ -210,6 +220,12 @@ export interface MessageHandlerContext {
      * are never persisted in Canon message metadata.
      */
     requestRuntimeInput: (request: RuntimeInputRequest) => Promise<RuntimeInputResult>;
+    /**
+     * Present a native Canon plan-review card and wait for approve, revise,
+     * reject, cancellation, or timeout. Canon owns presentation and response
+     * routing; the runtime remains responsible for enforcing the decision.
+     */
+    requestPlanReview: (request: RuntimePlanReviewRequest) => Promise<RuntimePlanReviewResult>;
     /**
      * Ask the triggering human to review/respond to a generic rich card. The
      * visible card document is redacted for presentation; raw response values
@@ -329,7 +345,6 @@ export interface CanonAgentOptions extends CanonAgentConnectionOptions {
      */
     turnVerbosity?: import('./turn-verbosity-option.js').CanonAgentTurnVerbosityOption;
 }
-export type ContactRequestHandler = (request: import('@canonmsg/core').CanonContactRequest) => void | Promise<void>;
 export type ContactAddedHandler = (contact: import('@canonmsg/core').ContactAddedPayload) => void | Promise<void>;
 export type ContactRemovedHandler = (payload: import('@canonmsg/core').ContactRemovedPayload) => void | Promise<void>;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-sdk",
-  "version": "9.0.0",
+  "version": "10.0.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": "^11.0.0"
+    "@canonmsg/core": "^12.0.0"
   },
   "publishConfig": {
     "access": "public"