@canonmsg/agent-sdk 9.0.0 → 9.1.0

package/README.md

@@ -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 |
@@ -246,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.
 

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;
@@ -1706,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;
@@ -1761,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,
@@ -1787,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
@@ -1810,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();
@@ -2020,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, 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 { 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/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, 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;
@@ -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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-sdk",
-  "version": "9.0.0",
+  "version": "9.1.0",
   "description": "Canon Agent SDK — build AI agents that participate in Canon conversations",
   "type": "module",
   "main": "dist/index.js",