@canonmsg/agent-sdk 8.9.0 → 9.1.0

package/README.md

@@ -53,29 +53,12 @@ The only runtime dependency is `@canonmsg/core`, which npm installs for you. Eve
 | `sessions` | `SessionOptions` | `undefined` | Enable per-conversation session queues and persistent metadata |
 | `clientType` | `AgentClientType` | `'generic'` | Agent runtime label used for Canon capability detection |
 | `runtimeDescriptor` | `CanonRuntimeDescriptor` | minimal generic descriptor | Optional setup/live controls and runtime capability metadata for Canon UI |
-| `ownerBoundCommunication` | `{ enabled: true, lifecycleStore? }` | `undefined` | Opt into owner-foreground `ctx.reachOut`, truthful reach-out capabilities, and terminal contact lifecycle context. Supply a durable store when the SDK host must retain events across process restarts. |
 | `runtimeControls` | `RuntimeControlHandlers` | `undefined` | Optional `onInterrupt` / `onStopAndDrop` / `onNewSession` handlers for Canon working-state controls |
 | `runtimeControlSurface` | `'agent' \| 'host'` | `'agent'` | Runtime publishing surface. Use `host` when this SDK agent owns live runtime controls. |
 | `runtimePrimitives` | `RuntimePrimitiveHandlers` | `undefined` | Optional typed primitive command handlers for descriptor-backed runtime commands |
 | `sessionState` | `boolean` | `false` | Publish runtime-applied state to the canonical agent-session snapshot |
 | `turnVerbosity` | `'verbose' \| 'quiet' \| 'auto'` or `{ direct?, group? }` | `'auto'` | How much of a turn's middle readers see. See [Turn verbosity](#turn-verbosity). |
 
-### Owner-bound agent introductions
-
-Enable `ownerBoundCommunication` only when your handler is the model-facing
-foreground surface. In that mode, `ctx.reachOut` requires an owner-authored
-source message and visible text, binds replies to the replied contact card, and
-rejects model-selected session setup or hidden self-context. Programmatic
-`agent.reachOut(...)` remains available for application-controlled workflows.
-
-Terminal outbound contact-request phases are deduplicated and exposed through
-`ctx.contactLifecycleEvents` on the next natural owner turn in the source
-conversation. The store records an initial baseline without replaying historical
-outcomes; persist its baseline, dedupe keys, and pending rows when restart
-recovery matters. The default store is process-local. Lifecycle events never
-invoke the message handler on their own, and `connected` means Canon has already
-delivered the opener.
-
 ### Optional runtime controls
 
 Generic SDK agents publish no setup controls by default. If your SDK runtime has local workspace access, you can opt in by publishing a descriptor with explicit project choices:
@@ -207,8 +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 |
-| `sendContextualMessage` | function | Send into another conversation with private self-context from this conversation |
-| `reachOut` | function | Act on a Canon contact card using live admission resolution |
+| `communicate` | function | Message an existing conversation, start a direct conversation, create a group, or forward an exact message |
 | `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 |
@@ -218,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 |
@@ -264,7 +247,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.
 
@@ -307,18 +290,9 @@ agent.on('contactRequest', (request) => {
 agent.on('contactApproved', (request) => {
   console.log('Request approved:', request.id);
 });
-
-agent.on('contactRequestUpdated', (request) => {
-  console.log('Outbound request phase:', request.phase);
-});
 ```
 
-These are awareness callbacks only. Canon still routes approval, rejection,
-and any coding-session setup for agent-targeted requests through the human
-owner's UI/callable flow. Outbound phases intentionally hide delivery internals:
-`awaiting_owner`, `starting`, `connected`, `rejected`, `expired`, `cancelled`,
-or `failed`. A connected update includes the conversation id and means the
-parked opener was already delivered; do not send it again.
+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
 
@@ -361,8 +335,6 @@ await agent.contacts.list();                       // CanonContact[]
 await agent.contacts.get(contactId);               // CanonContact | null
 await agent.contacts.remove(contactId);
 await agent.contacts.request(targetUserId, 'why I am reaching out');
-await agent.contacts.listRequests({ direction: 'outbound', includeResolved: true });
-await agent.contacts.cancelRequest(requestId);
 
 await agent.users.block(userId);
 await agent.users.unblock(userId);
@@ -536,7 +508,7 @@ A conversation whose type Canon could not determine falls back to verbose, never
 
 **Quiet suppresses**: every `/streaming` publication — the `'Thinking...'` seed and its keepalive, `turn.setThinking/setStreaming/setTool`, `turn.appendDelta`/`appendBlock`/segment updates, `turn.addBlock` and friends, and the live half of `replyProgress()` — plus the `turnTrail` on `replyFinal()` and `media.replyWithFile()`. Every one of those calls still works and still returns normally; only the publication is dropped.
 
-**Quiet does not suppress**: the typing/thinking indicator (which stays up for the turn's whole working phase; while the turn is parked on an approval the clients suppress an agent's dots and the header line carries the state), turn state, `replyFinal()` including every part of a chunked reply, the partial-final notice, `media.replyWithFile()` itself, `turn.setWaitingInput()`'s note, `sendContextualMessage()`, `publishRuntimeActivity()`, approval/input/card requests, and their outcome receipts.
+**Quiet does not suppress**: the typing/thinking indicator (which stays up for the turn's whole working phase; while the turn is parked on an approval the clients suppress an agent's dots and the header line carries the state), turn state, `replyFinal()` including every part of a chunked reply, the partial-final notice, `media.replyWithFile()` itself, `turn.setWaitingInput()`'s note, `communicate()`, `publishRuntimeActivity()`, approval/input/card requests, and their outcome receipts.
 
 **`replyProgress(text, { durable: true })` still posts.** Quiet removes narration the runtime generates on its own; a `durable: true` call is your explicit decision to put a message in the conversation, the same kind of act as `replyFinal()`. Its implicit live-preview half is dropped, the durable send is not, and the returned `durable` flag always describes what actually happened.
 
@@ -561,4 +533,4 @@ Canon caps a single message at 4 KB of UTF-8 text, and rejects anything longer o
 Every other send path passes your text through as-is, so text over the cap still fails there. Notably:
 
 - `media.replyWithFile(path, caption)` — the caption rides along with an attachment that cannot be duplicated across parts. Keep captions short and send long prose as a separate `replyFinal()`.
-- `sendContextualMessage()` and `reachOut({ text })` — a different endpoint with no chunked sender behind it.
+- `communicate()` — a distinct compact cross-conversation operation; keep each message under the cap.

package/dist/canon-agent.d.ts

@@ -1,5 +1,5 @@
-import { type AddMemberResult, type CanonContact, type CanonContactRequest, type ContactRequestListOptions, type CanonConversation, type CanonConversationsPage, type CanonConversationsPageOptions, type CreateConversationResult, type CanonRuntimeActivityItem, type CanonRuntimeCommandDescriptor, type CanonRuntimeFact, type CanonRuntimePrimitiveId, type ContactCardPayload, type ClearRuntimeActivityOptions, type CreateContactRequestResult, type CanonVoiceSession, type CanonVoiceSessionToken, type CreateVoiceSessionOptions, type VoiceSessionEventPayload } from '@canonmsg/core';
-import type { CanonAgentConnectionOptions, CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, CreateConversationOptions, MessageHandler, MessageUpdatedHandler, ParticipationSuppressedHandler, ReachOutOptions, ReachOutResult, ContactRequestHandler, ContactRequestUpdatedHandler, RuntimeSignalHandler, RuntimePrimitiveHandler } from './types.js';
+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';
 /**
  * Contact-graph operations exposed under `agent.contacts`. Wraps the REST
  * endpoints in CanonClient — the same surface a human user would hit through
@@ -9,12 +9,6 @@ export interface AgentContactsAPI {
     list(): Promise<CanonContact[]>;
     get(contactId: string): Promise<CanonContact | null>;
     remove(contactId: string): Promise<void>;
-    request(targetUserId: string, message?: string | null): Promise<CreateContactRequestResult>;
-    listRequests(options?: ContactRequestListOptions): Promise<CanonContactRequest[]>;
-    cancelRequest(requestId: string): Promise<{
-        status: 'cancelled';
-        requestId: string;
-    }>;
 }
 /**
  * User-level moderation actions exposed under `agent.users`.
@@ -47,7 +41,6 @@ export declare class CanonAgent {
     private sessionManager;
     private handler;
     private contactRequestHandler;
-    private contactRequestUpdatedHandler;
     private contactApprovedHandler;
     private contactAddedHandler;
     private contactRemovedHandler;
@@ -68,8 +61,6 @@ export declare class CanonAgent {
     readonly users: AgentUsersAPI;
     /** Conversation discovery for choosing existing sessions intentionally. */
     readonly conversations: AgentConversationsAPI;
-    private readonly reachOutInFlight;
-    private readonly contactLifecycleStore;
     private agentId;
     private agentContext;
     private approvalManager;
@@ -111,7 +102,6 @@ export declare class CanonAgent {
     on(event: 'message', handler: MessageHandler): void;
     on(event: 'messageUpdated', handler: MessageUpdatedHandler): void;
     on(event: 'contactRequest', handler: ContactRequestHandler): void;
-    on(event: 'contactRequestUpdated', handler: ContactRequestUpdatedHandler): void;
     on(event: 'contactApproved', handler: ContactRequestHandler): void;
     on(event: 'contactAdded', handler: ContactAddedHandler): void;
     on(event: 'contactRemoved', handler: ContactRemovedHandler): void;
@@ -135,16 +125,13 @@ export declare class CanonAgent {
     publishRuntimeActivity(conversationId: string, item: CanonRuntimeActivityItem): Promise<void>;
     clearRuntimeActivity(conversationId: string, options?: ClearRuntimeActivityOptions): Promise<void>;
     /**
-     * Resolve admission live for a target user (typically read off a shared
-     * contact card) and route into either an immediate message or a contact
-     * request. Never reads `card.accessLevel` — that snapshot is stale by the
-     * time an LLM acts on it. Instead defers to `resolveAdmission` so the
-     * answer reflects the target's *current* inbound policy.
+     * Message an existing Canon conversation or start/continue a direct one.
+     * Policy and admission are enforced by Canon; this method deliberately
+     * exposes no runtime configuration or trusted source-context fields.
      */
-    reachOut(card: ContactCardPayload, options?: ReachOutOptions): Promise<ReachOutResult>;
-    private executeReachOut;
+    communicate(input: CommunicateInput): Promise<CommunicateResult>;
     start(): Promise<void>;
-    createConversation(options: CreateConversationOptions): Promise<CreateConversationResult>;
+    createGroup(options: CreateGroupOptions): Promise<CreateGroupResult>;
     /** Start (or rejoin) a call in a conversation and get the room token. */
     startCall(options: CreateVoiceSessionOptions): Promise<CanonVoiceSessionToken>;
     /** Join an active call session and get the room token. */
@@ -179,8 +166,6 @@ export declare class CanonAgent {
         attachment: import('@canonmsg/core').MediaAttachment;
     }>;
     private handleContactRequestEvent;
-    private recordAndHandleContactLifecycleEvent;
-    private reconcileContactLifecycleInbox;
     private handleContactGraphEvent;
     private handleParticipationSuppressedEvent;
     private handleMessageUpdatedEvent;

package/dist/canon-agent.js

@@ -1,4 +1,4 @@
-import { ApprovalManager, RuntimeRequestManager, runtimeInputDescriptor, runtimeCardDescriptor, CanonClient, ControlChannelPoller, buildCanonTurnContextV2, buildCanonGroupContext, buildParticipationHistorySnapshot, createTurnOutputController, createRuntimeStatePublisher, createTypingStatusPublisher, diffCanonMemberIds, contactRequestLifecycleEventKey, reconcileContactLifecycleEvents, FINAL_MESSAGE_HANDOFF_MS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildRuntimeCardOutcome, buildRuntimeInputOutcome, initRTDBAuth, isChunkedSendMessageError, normalizeRuntimeCommandDescriptors, normalizeTurnMetadata, normalizeTurnVerbosityConversationType, reachOutToCanonContact, 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, 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 { createHash, randomUUID } from 'node:crypto';
 import { AuthManager } from './auth.js';
 import { Debouncer } from './debouncer.js';
@@ -15,34 +15,6 @@ const SDK_MESSAGE_ID_READABLE_MAX = 120;
 /** Canon's message id ceiling, matching core's chunked sender. */
 const CANON_MESSAGE_ID_MAX = 160;
 const SDK_PARTIAL_FINAL_NOTICE = 'This reply stops short because Canon could not deliver the remaining text.';
-class InMemoryContactLifecycleStore {
-    keys = new Set();
-    pending = [];
-    baselineComplete = false;
-    record(request, options = {}) {
-        const key = contactRequestLifecycleEventKey(request);
-        if (!key || this.keys.has(key))
-            return false;
-        this.keys.add(key);
-        if (options.pending !== false)
-            this.pending.push(request);
-        while (this.keys.size > 512)
-            this.keys.delete(this.keys.values().next().value);
-        this.pending = this.pending.slice(-100);
-        return true;
-    }
-    take(sourceConversationId) {
-        const taken = this.pending.filter((request) => request.sourceConversationId === sourceConversationId);
-        this.pending = this.pending.filter((request) => request.sourceConversationId !== sourceConversationId);
-        return taken;
-    }
-    isBaselineComplete() {
-        return this.baselineComplete;
-    }
-    completeBaseline() {
-        this.baselineComplete = true;
-    }
-}
 const SDK_RUNTIME_CAPABILITIES = {
     supportsInterrupt: false,
     supportsInputInterrupt: false,
@@ -273,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;
@@ -283,7 +282,6 @@ export class CanonAgent {
     sessionManager = null;
     handler = null;
     contactRequestHandler = null;
-    contactRequestUpdatedHandler = null;
     contactApprovedHandler = null;
     contactAddedHandler = null;
     contactRemovedHandler = null;
@@ -304,8 +302,6 @@ export class CanonAgent {
     users;
     /** Conversation discovery for choosing existing sessions intentionally. */
     conversations;
-    reachOutInFlight = new Map();
-    contactLifecycleStore;
     agentId = null;
     agentContext = null;
     approvalManager = null;
@@ -352,9 +348,6 @@ export class CanonAgent {
             rtdbUrl: this.runtimeConnection.rtdbUrl,
             firebaseApiKey: this.runtimeConnection.firebaseWebApiKey,
         };
-        this.contactLifecycleStore = options.ownerBoundCommunication?.enabled
-            ? options.ownerBoundCommunication.lifecycleStore ?? new InMemoryContactLifecycleStore()
-            : null;
         this.apiClient = new CanonClient(this.options.apiKey, this.options.baseUrl);
         this.typingSignals = createTypingStatusPublisher({
             setTyping: (conversationId, typing, status) => status
@@ -368,9 +361,6 @@ export class CanonAgent {
             list: () => apiClient.listContacts(),
             get: (contactId) => apiClient.getContact(contactId),
             remove: (contactId) => apiClient.deleteContact(contactId),
-            request: (targetUserId, message) => apiClient.createContactRequest(targetUserId, message ?? null),
-            listRequests: (options) => apiClient.listContactRequests(options),
-            cancelRequest: (requestId) => apiClient.cancelContactRequest(requestId),
         };
         this.users = {
             block: (userId) => apiClient.blockUser(userId),
@@ -498,10 +488,6 @@ export class CanonAgent {
             this.contactRequestHandler = handler;
             return;
         }
-        if (event === 'contactRequestUpdated') {
-            this.contactRequestUpdatedHandler = handler;
-            return;
-        }
         if (event === 'contactApproved') {
             this.contactApprovedHandler = handler;
             return;
@@ -585,75 +571,12 @@ export class CanonAgent {
         await this.requireRuntimeStatePublisher().clearRuntimeActivity(conversationId, options);
     }
     /**
-     * Resolve admission live for a target user (typically read off a shared
-     * contact card) and route into either an immediate message or a contact
-     * request. Never reads `card.accessLevel` — that snapshot is stale by the
-     * time an LLM acts on it. Instead defers to `resolveAdmission` so the
-     * answer reflects the target's *current* inbound policy.
+     * Message an existing Canon conversation or start/continue a direct one.
+     * Policy and admission are enforced by Canon; this method deliberately
+     * exposes no runtime configuration or trusted source-context fields.
      */
-    async reachOut(card, options) {
-        const target = {
-            targetUserId: card.userId,
-            ...(card.userType === 'ai_agent' && card.canonContactId
-                ? { canonContactId: card.canonContactId }
-                : {}),
-        };
-        const targetKey = target.canonContactId ?? target.targetUserId;
-        // Include the opener/request payloads in the dedupe key so two concurrent
-        // calls with different `text`, `requestMessage`, or setup choices don't silently collapse
-        // and lose the second caller's intended side effect.
-        const contextualKey = options?.selfContext
-            ? `${options.sourceConversationId ?? ''}\u0000${options.selfContext.type}\u0000${options.selfContext.context}`
-            : '';
-        const inFlightKey = `${targetKey}\u0000${options?.text ?? ''}\u0000${options?.requestMessage ?? ''}\u0000${JSON.stringify(options?.sessionConfig ?? null)}\u0000${JSON.stringify(options?.sessionSelection ?? null)}\u0000${contextualKey}`;
-        const inFlight = this.reachOutInFlight.get(inFlightKey);
-        if (inFlight)
-            return inFlight;
-        const promise = this.executeReachOut(target, options).finally(() => {
-            this.reachOutInFlight.delete(inFlightKey);
-        });
-        this.reachOutInFlight.set(inFlightKey, promise);
-        return promise;
-    }
-    async executeReachOut(target, options) {
-        const { targetUserId } = target;
-        if (options?.selfContext) {
-            if (!options.sourceConversationId) {
-                throw new Error('sourceConversationId is required for contextual reachOut');
-            }
-            if (!options.text) {
-                throw new Error('text is required for contextual reachOut');
-            }
-            const result = await this.apiClient.sendContextualMessage({
-                sourceConversationId: options.sourceConversationId,
-                targetUserId,
-                text: options.text,
-                selfContext: options.selfContext,
-                requestMessage: options.requestMessage ?? null,
-                sessionConfig: options.sessionConfig ?? null,
-                sessionSelection: options.sessionSelection,
-            });
-            return result.status === 'messaged'
-                ? {
-                    status: 'messaged',
-                    conversationId: result.conversationId,
-                    messageId: result.messageId,
-                    selfContextId: result.selfContextId,
-                    created: result.created,
-                    reused: result.reused,
-                    sessionSelection: result.sessionSelection,
-                }
-                : result;
-        }
-        return reachOutToCanonContact(this.apiClient, {
-            ...(target.canonContactId
-                ? { canonContactId: target.canonContactId }
-                : { targetUserId }),
-            text: options?.text ?? null,
-            requestMessage: options?.requestMessage ?? null,
-            sessionConfig: options?.sessionConfig ?? null,
-            sessionSelection: options?.sessionSelection,
-        });
+    async communicate(input) {
+        return this.apiClient.communicate(input);
     }
     async start() {
         if (this.running)
@@ -702,7 +625,6 @@ export class CanonAgent {
         try {
             this.agentContext = await this.apiClient.getAgentMe();
             this.ensureApprovalManager(this.agentContext);
-            await this.reconcileContactLifecycleInbox();
         }
         catch {
             console.warn('[canon-sdk] Failed to fetch agent context — owner/access info unavailable');
@@ -749,9 +671,6 @@ export class CanonAgent {
             onContactRequest: (request) => {
                 void this.handleContactRequestEvent(this.contactRequestHandler, request);
             },
-            onContactRequestUpdated: (request) => {
-                void this.recordAndHandleContactLifecycleEvent(request);
-            },
             onContactApproved: (request) => {
                 void this.handleContactRequestEvent(this.contactApprovedHandler, request);
             },
@@ -781,26 +700,18 @@ export class CanonAgent {
         rtm.setConnectionHandlers({
             onConnected: () => {
                 this.startRuntimeHeartbeat();
-                void this.reconcileContactLifecycleInbox().catch((error) => {
-                    console.error('[canon-sdk] Contact lifecycle reconciliation failed:', error);
-                });
                 if (!this.sseConnectedLogged) {
                     this.sseConnectedLogged = true;
                     console.log('[canon-sdk] SSE stream connected');
                 }
             },
-            onReplayExpired: () => {
-                void this.reconcileContactLifecycleInbox().catch((error) => {
-                    console.error('[canon-sdk] Contact lifecycle reconciliation failed:', error);
-                });
-            },
             onDisconnected: () => this.stopRuntimeHeartbeat(),
         });
         this.realtimeManager = rtm;
         await rtm.start();
     }
-    async createConversation(options) {
-        return this.apiClient.createConversation(options);
+    async createGroup(options) {
+        return this.apiClient.createGroup(options);
     }
     // ── Calls ────────────────────────────────────────────────────────────
     // These return the LiveKit room token payload; the agent brings its own
@@ -869,37 +780,6 @@ export class CanonAgent {
             console.error('[canon-sdk] Contact-request handler failed:', error instanceof Error ? error.message : error);
         }
     }
-    async recordAndHandleContactLifecycleEvent(request) {
-        if (this.contactLifecycleStore
-            && request.requesterId === this.agentId
-            && request.sourceConversationId) {
-            await this.contactLifecycleStore.record(request);
-        }
-        await this.handleContactRequestEvent(this.contactRequestUpdatedHandler, request);
-    }
-    async reconcileContactLifecycleInbox() {
-        if (!this.contactLifecycleStore || !this.agentId)
-            return;
-        const requests = await this.apiClient.listContactRequests({
-            direction: 'outbound',
-            includeResolved: true,
-            limit: 100,
-        });
-        if (!await this.contactLifecycleStore.isBaselineComplete()) {
-            await reconcileContactLifecycleEvents({
-                requests,
-                requesterId: this.agentId,
-                record: (request) => this.contactLifecycleStore.record(request, { pending: false }),
-            });
-            await this.contactLifecycleStore.completeBaseline();
-            return;
-        }
-        await reconcileContactLifecycleEvents({
-            requests,
-            requesterId: this.agentId,
-            record: (request) => this.contactLifecycleStore.record(request),
-        });
-    }
     async handleContactGraphEvent(handler, payload) {
         if (!handler)
             return;
@@ -1016,13 +896,6 @@ export class CanonAgent {
         }
         return {
             ...source,
-            admissionActions: {
-                blockUser: source.admissionActions?.blockUser === true,
-                unblockUser: source.admissionActions?.unblockUser === true,
-                removeContact: source.admissionActions?.removeContact === true,
-                requestContact: this.options.ownerBoundCommunication?.enabled === true,
-                reachOut: this.options.ownerBoundCommunication?.enabled === true,
-            },
             supportsInterrupt: hasInterrupt,
             supportsInputInterrupt: source.supportsInputInterrupt === false ? false : hasInterrupt,
             commands: normalizeRuntimeCommandDescriptors(commands),
@@ -1631,9 +1504,6 @@ export class CanonAgent {
                 for (const m of history) {
                     m.isOwner = m.senderId === ownerId;
                 }
-                for (const m of hydratedMessages) {
-                    m.isOwner = m.senderId === ownerId;
-                }
             }
             const latestMessage = hydratedMessages[hydratedMessages.length - 1] ?? null;
             const triggeringHumanId = latestMessage?.senderType === 'human'
@@ -1642,9 +1512,6 @@ export class CanonAgent {
             let replyContext = latestMessage
                 ? resolveCanonReplyContext({ message: latestMessage, messages: history })
                 : null;
-            const contactLifecycleEvents = latestMessage?.isOwner && this.contactLifecycleStore
-                ? await this.contactLifecycleStore.take(conversationId)
-                : [];
             const resolvedActiveSelfContextId = resolveMessageActiveSelfContextId({
                 messageId: latestMessage?.id,
                 activeSelfContextIdByMessageId: page.activeSelfContextIdByMessageId,
@@ -1708,6 +1575,7 @@ export class CanonAgent {
                 ownerName: '',
                 discoverable: false,
                 inboundPolicy: 'approval-required',
+                outboundPolicy: 'approval-required',
                 groupJoinPolicy: 'approval-required',
             };
             const provenance = latestMessage
@@ -1797,58 +1665,7 @@ export class CanonAgent {
             const react = (messageId, emoji) => this.apiClient.react(conversationId, messageId, emoji);
             const addMember = (userId) => this.apiClient.addMember(conversationId, userId);
             const removeMember = (userId) => this.apiClient.removeMember(conversationId, userId);
-            const sendContextualMessage = (target, text, options) => this.apiClient.sendContextualMessage({
-                sourceConversationId: conversationId,
-                ...target,
-                text,
-                ...options,
-                messageOptions: {
-                    ...(options.messageOptions ?? {}),
-                    metadata: {
-                        ...(options.messageOptions?.metadata ?? {}),
-                        turnId,
-                        turnSemantics: 'turn_complete',
-                    },
-                },
-            });
-            const reachOut = (card, options) => {
-                if (!this.options.ownerBoundCommunication?.enabled) {
-                    return this.reachOut(card, {
-                        ...(options ?? {}),
-                        sourceConversationId: conversationId,
-                    });
-                }
-                if (!latestMessage?.isOwner || !latestMessage.id) {
-                    return Promise.reject(new Error('Owner-bound reachOut requires an owner-authored foreground message.'));
-                }
-                if (options?.sessionConfig != null
-                    || options?.sessionSelection != null
-                    || options?.selfContext != null) {
-                    return Promise.reject(new Error('Owner-bound reachOut does not accept model-selected session configuration or hidden context.'));
-                }
-                const boundCard = replyContext?.found && replyContext.contactCard
-                    ? replyContext.contactCard
-                    : card;
-                const text = options?.text?.trim();
-                if (!text)
-                    return Promise.reject(new Error('Owner-bound reachOut requires visible text.'));
-                return this.apiClient.sendTo({
-                    ...(boundCard.canonContactId
-                        ? { canonContactId: boundCard.canonContactId }
-                        : { targetUserId: boundCard.userId }),
-                    sourceConversationId: conversationId,
-                    text,
-                    ...(options?.requestMessage ? { requestMessage: options.requestMessage } : {}),
-                    messageOptions: {
-                        metadata: {
-                            sourceConversationId: conversationId,
-                            sourceMessageId: latestMessage.id,
-                            turnId,
-                            turnSemantics: 'turn_complete',
-                        },
-                    },
-                });
-            };
+            const communicate = (input) => this.communicate(input);
             const requestApproval = async (request) => {
                 throwIfAborted();
                 const manager = this.ensureApprovalManager(agent);
@@ -1916,6 +1733,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;
@@ -1971,7 +1789,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,
@@ -1997,7 +1815,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
@@ -2020,6 +1838,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();
@@ -2209,7 +2102,6 @@ export class CanonAgent {
                 messages: hydratedMessages,
                 history,
                 replyContext,
-                contactLifecycleEvents,
                 conversationId,
                 conversation,
                 ...(groupContext ? { groupContext } : {}),
@@ -2221,8 +2113,7 @@ export class CanonAgent {
                 react,
                 addMember,
                 removeMember,
-                sendContextualMessage,
-                reachOut,
+                communicate,
                 agent,
                 activeSelfContextId,
                 selfContexts,
@@ -2232,6 +2123,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, ContactRequestUpdatedPayload, ContactRequestListOptions, ContactRequestRequirements, ContactRequestLifecyclePhase, GroupInviteRequirements, CanonMessage, CanonConversation, CanonConversationsPage, CanonConversationsPageOptions, CanonReplyContext, CanonSelfContext, CanonTurnContextV2, CanonRuntimeDescriptor, MessageUpdatedPayload, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, CreateConversationOptions, CreateConversationResult, DirectSessionSelection, TurnVerbosity, TurnVerbosityConfig, } from '@canonmsg/core';
-export type { CanonAgentConnectionOptions, CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, ContactRequestHandler, ContactRequestUpdatedHandler, ContactLifecycleStore, FinalMessageResult, MessageHandler, MessageHandlerContext, MessageUpdatedHandler, ParticipationSuppressedHandler, ProgressMessageOptions, ProgressMessageResult, ReachOutOptions, ReachOutResult, RuntimeApprovalRequest, RuntimeInputRequest, RuntimeInputResult, RuntimeControlSurface, RuntimePrimitiveContext, RuntimePrimitiveHandler, RuntimePrimitiveHandlers, SessionInfo, SessionOptions, DeliveryMode, } from './types.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, 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 ContactRequestUpdatedPayload, type ConversationUpdatedPayload, type MessageUpdatedPayload, type ParticipationSuppressedPayload, type VoiceSessionEventPayload } from '@canonmsg/core';
+import { type AgentContext, type ContactAddedPayload, type ContactApprovedPayload, type ContactRemovedPayload, type ContactRequestPayload, 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:
@@ -16,7 +16,6 @@ export declare class RealtimeManager {
     private suppressedSseErrorCount;
     private onAgentContext;
     private onContactRequest;
-    private onContactRequestUpdated;
     private onContactApproved;
     private onContactAdded;
     private onContactRemoved;
@@ -26,7 +25,6 @@ export declare class RealtimeManager {
     private onMessageDeleted;
     private onConnected;
     private onDisconnected;
-    private onReplayExpired;
     private onCallStarted;
     private onCallEnded;
     constructor(apiKey: string, debouncer: Debouncer, agentId: string, streamUrl?: string, options?: {
@@ -39,7 +37,6 @@ export declare class RealtimeManager {
     setOnAgentContext(cb: (ctx: AgentContext) => void): void;
     setContactRequestHandlers(handlers: {
         onContactRequest?: (payload: ContactRequestPayload) => void;
-        onContactRequestUpdated?: (payload: ContactRequestUpdatedPayload) => void;
         onContactApproved?: (payload: ContactApprovedPayload) => void;
     }): void;
     setContactGraphHandlers(handlers: {
@@ -61,7 +58,6 @@ export declare class RealtimeManager {
     setConnectionHandlers(handlers: {
         onConnected?: () => void;
         onDisconnected?: () => void;
-        onReplayExpired?: () => void;
     }): void;
     setCallHandlers(handlers: {
         onCallStarted?: (payload: VoiceSessionEventPayload) => void;

package/dist/realtime.js

@@ -17,7 +17,6 @@ export class RealtimeManager {
     suppressedSseErrorCount = 0;
     onAgentContext = null;
     onContactRequest = null;
-    onContactRequestUpdated = null;
     onContactApproved = null;
     onContactAdded = null;
     onContactRemoved = null;
@@ -27,7 +26,6 @@ export class RealtimeManager {
     onMessageDeleted = null;
     onConnected = null;
     onDisconnected = null;
-    onReplayExpired = null;
     onCallStarted = null;
     onCallEnded = null;
     constructor(apiKey, debouncer, agentId, streamUrl, options) {
@@ -104,9 +102,6 @@ export class RealtimeManager {
                 onContactRequest: (payload) => {
                     this.onContactRequest?.(payload);
                 },
-                onContactRequestUpdated: (payload) => {
-                    this.onContactRequestUpdated?.(payload);
-                },
                 onContactApproved: (payload) => {
                     this.onContactApproved?.(payload);
                 },
@@ -130,7 +125,6 @@ export class RealtimeManager {
                 },
                 onReplayExpired: (payload) => {
                     console.error(`[canon-sdk] SSE replay window expired${payload.lastAvailableId ? ` (oldest available event: ${payload.lastAvailableId})` : ''}; missed history is available via explicit REST fetch`);
-                    this.onReplayExpired?.();
                 },
                 onError: (err) => {
                     this.logSseError(err);
@@ -181,7 +175,6 @@ export class RealtimeManager {
     }
     setContactRequestHandlers(handlers) {
         this.onContactRequest = handlers.onContactRequest ?? null;
-        this.onContactRequestUpdated = handlers.onContactRequestUpdated ?? null;
         this.onContactApproved = handlers.onContactApproved ?? null;
     }
     setContactGraphHandlers(handlers) {
@@ -208,7 +201,6 @@ export class RealtimeManager {
     setConnectionHandlers(handlers) {
         this.onConnected = handlers.onConnected ?? null;
         this.onDisconnected = handlers.onDisconnected ?? null;
-        this.onReplayExpired = handlers.onReplayExpired ?? null;
     }
     setCallHandlers(handlers) {
         this.onCallStarted = handlers.onCallStarted ?? null;

package/dist/types.d.ts

@@ -1,5 +1,5 @@
-export type { AddMemberResult, ContactRequestListOptions, ContactRequestRequirements, ContactRequestLifecyclePhase, GroupInviteRequirements, AgentClientType, CanonGroupContext, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeDescriptor, CanonRuntimeFact, CanonRuntimeFactGroup, CanonRuntimePrimitiveId, CanonRuntimeProvenance, CanonTurnContextV2, CanonMessage, CanonConversation, CanonReplyContext, CanonContact, CanonContactRequest, ContactRequestUpdatedPayload, CanonResolveAdmissionResult, ContactAddedPayload, ContactRemovedPayload, ContactSource, AgentContext, ResolveAdmissionTargetInput, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonSelfContext, CreateConversationResult, DirectSessionSelection, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, SessionConfig, VerbSessionConfig, CreateConversationOptions, 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, CanonReplyContext, ContactCardPayload, CanonRuntimeActionDispatch, CanonRuntimePrimitiveId, CanonRuntimeProvenance, CanonTurnContextV2, ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalResult, ApprovalRisk, RuntimeInputChoice, RuntimeInputAnswers, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, RuntimeCardNativeMetadata, RuntimeCardV1, ResumableMediaUploadResult, SendMessageOptions, SendContextualSelfContextInput, VerbSessionConfig, DirectSessionSelection, TurnOutputBlock, TurnOutputBlockInput } from '@canonmsg/core';
+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, 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;
@@ -152,8 +162,6 @@ export interface MessageHandlerContext {
     history: CanonMessage[];
     /** Resolved message/media content for the latest swipe-reply target, if any. */
     replyContext: CanonReplyContext | null;
-    /** Terminal introduction events retained until this natural owner turn. */
-    contactLifecycleEvents: import('@canonmsg/core').CanonContactRequest[];
     conversationId: string;
     conversation: CanonConversation;
     /** Lightweight group awareness, present for group conversations. */
@@ -178,14 +186,8 @@ export interface MessageHandlerContext {
     addMember: (userId: string) => Promise<AddMemberResult>;
     /** Remove a member from this conversation (requires owner/admin role) */
     removeMember: (userId: string) => Promise<void>;
-    /** Send into another Canon conversation with private cross-session self-context. */
-    sendContextualMessage: (target: {
-        targetConversationId: string;
-    } | {
-        targetUserId: string;
-    }, text: string, options: Omit<import('@canonmsg/core').SendContextualMessageOptions, 'sourceConversationId' | 'targetConversationId' | 'targetUserId' | 'text'>) => Promise<import('@canonmsg/core').SendContextualMessageResult>;
-    /** Reach a contact card from this conversation; contextual reach-outs use this conversation as source. */
-    reachOut: (card: ContactCardPayload, options?: Omit<ReachOutOptions, 'sourceConversationId'>) => Promise<ReachOutResult>;
+    /** Message an existing Canon conversation or start/continue a direct one. */
+    communicate: (input: CommunicateInput) => Promise<CommunicateResult>;
     /** Trusted agent identity & access context */
     agent: import('@canonmsg/core').AgentContext;
     /** Active private self-context to continue for this turn, if Canon supplied one. */
@@ -218,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
@@ -312,15 +320,6 @@ export interface CanonAgentOptions extends CanonAgentConnectionOptions {
     clientType?: import('@canonmsg/core').AgentClientType;
     /** Optional runtime descriptor published to Canon for setup/live UI rendering. */
     runtimeDescriptor?: import('@canonmsg/core').CanonRuntimeDescriptor;
-    /**
-     * Opt into the owner-authorized introduction surface advertised to Canon.
-     * Lifecycle events never start a model turn; they are passed to the next
-     * natural owner handler invocation and to onContactRequestUpdated.
-     */
-    ownerBoundCommunication?: {
-        enabled: true;
-        lifecycleStore?: ContactLifecycleStore;
-    };
     /** Optional Canon runtime signal handlers. Enables interrupt controls when provided. */
     runtimeControls?: RuntimeControlHandlers;
     /** Runtime publishing surface. Use `host` when this agent owns live runtime controls. */
@@ -347,15 +346,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 ContactRequestUpdatedHandler = ContactRequestHandler;
-export interface ContactLifecycleStore {
-    record(request: import('@canonmsg/core').CanonContactRequest, options?: {
-        pending?: boolean;
-    }): boolean | Promise<boolean>;
-    take(sourceConversationId: string): import('@canonmsg/core').CanonContactRequest[] | Promise<import('@canonmsg/core').CanonContactRequest[]>;
-    isBaselineComplete(): boolean | Promise<boolean>;
-    completeBaseline(): 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>;
 /**
@@ -365,56 +355,3 @@ export type ContactRemovedHandler = (payload: import('@canonmsg/core').ContactRe
  * benched agent can tell deliberate participation policy from a dead stream.
  */
 export type ParticipationSuppressedHandler = (payload: import('@canonmsg/core').ParticipationSuppressedPayload) => void | Promise<void>;
-/**
- * Result of `agent.reachOut(card)` — describes which side-effect ran so the
- * caller can decide what to tell the LLM. `messaged` means the agent opened
- * (or sent into) a direct conversation; `requested` means the target's
- * inbound policy required a contact request, which has been created;
- * `pending` means a prior outbound request is still awaiting approval; and
- * `blocked` / `unavailable` describe terminal states with `reason` set.
- */
-export type ReachOutResult = {
-    status: 'messaged';
-    conversationId: string;
-    messageId?: string;
-    selfContextId?: string;
-    created?: boolean;
-    reused?: boolean;
-    sessionSelection?: DirectSessionSelection['mode'];
-} | {
-    status: 'requested';
-    requestId: string | null;
-    deferredIntentId?: string | null;
-} | {
-    status: 'pending';
-    requestId: string | null;
-    deferredIntentId?: string | null;
-} | {
-    status: 'setup_required';
-    reason: string;
-} | {
-    status: 'no_session';
-    reason: string;
-} | {
-    status: 'blocked' | 'unavailable';
-    reason: string;
-};
-export interface ReachOutOptions {
-    /**
-     * Optional first message; sent now when allowed or parked for exact delivery
-     * after approval when it is visible text <= 4 KiB. Attachments and hidden
-     * session setup cannot be parked; a setup-requiring coding target returns
-     * `setup_required` before a contact request is created.
-     */
-    text?: string;
-    /** Optional contact-request note. Defaults to `text` when admission is `request-required`. */
-    requestMessage?: string;
-    /** Explicit session setup to use when the contact-card target is an agent. */
-    sessionConfig?: VerbSessionConfig | null;
-    /** Whether to continue an existing direct agent session or start a fresh one. */
-    sessionSelection?: DirectSessionSelection;
-    /** Source conversation for contextual cross-session reach-outs. */
-    sourceConversationId?: string;
-    /** Private context for the agent when this reach-out sends a cross-session message. */
-    selfContext?: SendContextualSelfContextInput;
-}

package/package.json

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