@canonmsg/core 1.1.0 → 1.2.0

package/dist/browser.d.ts

@@ -1,7 +1,7 @@
 export { AGENT_CAPABILITIES, CLAUDE_PERMISSION_MODE_OPTIONS, } from './types.js';
 export { resolveCanonBaseUrl } from './base-url.js';
 export { DEFAULT_BASE_URL, DEFAULT_STREAM_URL, DEFAULT_RTDB_URL, FIREBASE_WEB_API_KEY } from './constants.js';
-export type { AddMemberResult, AgentCapabilities, AgentClientType, AgentSessionSnapshot, AgentRuntime, CanonControlAvailability, CanonControlDescriptor, CanonControlLiveBehavior, CanonControlSelectionPolicy, CanonControlValue, CanonContact, CanonContactRequest, CanonContactRequestStatus, CanonResolveAdmissionResult, ContactAddedPayload, ContactApprovedPayload, ContactRemovedPayload, ContactRequestPayload, ContactSource, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonStreamEvent, CreateContactRequestResult, MediaAttachment, MediaAttachmentKind, ModelOption, PermissionModeOption, CanonRuntimeDescriptor, CanonRuntimeActionAvailability, CanonRuntimeActionCategory, CanonRuntimeActionDescriptor, CanonRuntimeActionDispatch, CanonRuntimeActionPlacement, CanonRuntimeCommandArgumentChoice, CanonRuntimeCommandArgumentDescriptor, CanonRuntimeCommandArgumentKind, CanonRuntimeCommandDescriptor, CanonRuntimeDetailTier, CanonRuntimeExecutionMetadata, CanonRuntimePresentationField, CanonRuntimePresentationHint, CanonRuntimePresentationPolicy, CanonRuntimePresentationPreset, CanonRuntimeVisibility, CanonRuntimeProvenance, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeFact, CanonRuntimeFactGroup, CanonRuntimeInventory, CanonRuntimeInventoryEntry, CanonRuntimePrimitiveId, CanonRuntimeStreamingMode, CanonRuntimeStatusItem, CanonRuntimeSurfaceMode, CanonWorkspaceRootMetadata, RuntimeUpdatedPayload, RuntimeInfoPayload, RuntimeControlError, RuntimeControlState, RuntimeControlValueSource, ResolvedAdmission, SessionConfig, TurnOutputBlock, TurnOutputBlockKind, TurnOutputBlockStatus, TurnUpdatedPayload, WorkspaceOption, WorkspaceOptionSource, } from './types.js';
+export type { AddMemberResult, AgentCapabilities, AgentClientType, AgentSessionSnapshot, AgentRuntime, CanonControlAvailability, CanonControlDescriptor, CanonControlLiveBehavior, CanonControlSelectionPolicy, CanonControlValue, CanonRuntimeCardCapabilities, CanonRuntimeRichCardCapability, CanonContact, CanonContactRequest, CanonContactRequestStatus, CanonResolveAdmissionResult, ContactAddedPayload, ContactApprovedPayload, ContactRemovedPayload, ContactRequestPayload, ContactSource, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonStreamEvent, CreateContactRequestResult, MediaAttachment, MediaAttachmentKind, ModelOption, PermissionModeOption, CanonRuntimeDescriptor, CanonRuntimeActionAvailability, CanonRuntimeActionCategory, CanonRuntimeActionDescriptor, CanonRuntimeActionDispatch, CanonRuntimeActionPlacement, CanonRuntimeCommandArgumentChoice, CanonRuntimeCommandArgumentDescriptor, CanonRuntimeCommandArgumentKind, CanonRuntimeCommandDescriptor, CanonRuntimeDetailTier, CanonRuntimeExecutionMetadata, CanonRuntimePresentationField, CanonRuntimePresentationHint, CanonRuntimePresentationPolicy, CanonRuntimePresentationPreset, CanonRuntimeVisibility, CanonRuntimeProvenance, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeFact, CanonRuntimeFactGroup, CanonRuntimeInventory, CanonRuntimeInventoryEntry, CanonRuntimePrimitiveId, CanonRuntimeStreamingMode, CanonRuntimeStatusItem, CanonRuntimeSurfaceMode, CanonWorkspaceRootMetadata, RuntimeUpdatedPayload, RuntimeInfoPayload, RuntimeControlError, RuntimeControlState, RuntimeControlValueSource, ResolvedAdmission, SessionConfig, TurnOutputBlock, TurnOutputBlockKind, TurnOutputBlockStatus, TurnUpdatedPayload, WorkspaceOption, WorkspaceOptionSource, } from './types.js';
 export { DEFAULT_FIRST_PARTY_RUNTIME_PRESENTATION, RUNTIME_PRESENTATION_FIELDS, buildRuntimePresentationPolicy, getRuntimePresentationHint, isRuntimePresentationField, isRuntimePresentationFieldHidden, redactAgentSessionSnapshotForConversation, redactExecutionMetadataForConversation, redactRuntimeDescriptorForConversation, redactRuntimeInfoForConversation, } from './runtime-presentation.js';
 export { buildRuntimeProvenance, resolveRuntimeProvenance, } from './provenance.js';
 export { EXECUTION_ENVIRONMENT_MODES, isExecutionEnvironmentMode, } from './execution-environment-mode.js';
@@ -17,7 +17,7 @@ export type { DeliveryIntent, InboundDisposition, RuntimeCapabilities, TriggerDe
 export { buildApprovalReply, buildApprovalRequest, buildApprovalOutcome, generateApprovalId, redactSecrets, } from './approval-format.js';
 export type { ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalNativeRequestMetadata, ApprovalRisk, ApprovalReplyMetadata, ApprovalOutcomeMetadata, SessionRule, ApprovalResult, ApprovalConfig, } from './approval-types.js';
 export { DEFAULT_APPROVAL_CONFIG, parseApprovalRequestMetadata, parseApprovalReplyMetadata, parseSessionRule, } from './approval-types.js';
-export { buildRuntimeInputOutcome, buildRuntimeInputReply, buildRuntimeInputRequest, buildPlanApprovalReply, buildPlanApprovalRequest, buildQuestionReply, buildQuestionRequest, parseRuntimeInputOutcomeMetadata, parseRuntimeInputReplyMetadata, parseRuntimeInputRequestMetadata, } from './runtime-cards.js';
-export type { ClaudeQuestionMetadata, ClaudeQuestionReplyMetadata, PlanApprovalMetadata, PlanApprovalReplyMetadata, RuntimeInputAnswers, RuntimeInputChoice, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputOutcomeMetadata, RuntimeInputQuestion, RuntimeInputReplyMetadata, RuntimeInputReplyStatus, RuntimeInputRequestMetadata, RuntimeInputResolutionStatus, RuntimeQuestionDefinition, RuntimeQuestionOption, } from './runtime-cards.js';
+export { RUNTIME_CARD_SCHEMA_V1, buildRuntimeCardOutcome, buildRuntimeCardPreview, buildRuntimeCardReply, buildRuntimeCardRequest, buildRuntimeInputOutcome, buildRuntimeInputReply, buildRuntimeInputRequest, buildPlanApprovalReply, buildPlanApprovalRequest, buildQuestionReply, buildQuestionRequest, parseRuntimeCardOutcomeMetadata, parseRuntimeCardReplyMetadata, parseRuntimeCardRequestMetadata, parseRuntimeCardV1, parseRuntimeInputOutcomeMetadata, parseRuntimeInputReplyMetadata, parseRuntimeInputRequestMetadata, } from './runtime-cards.js';
+export type { ClaudeQuestionMetadata, ClaudeQuestionReplyMetadata, PlanApprovalMetadata, PlanApprovalReplyMetadata, RuntimeCardAction, RuntimeCardActionsBlock, RuntimeCardBlock, RuntimeCardBlockKind, RuntimeCardCalloutBlock, RuntimeCardChartBlock, RuntimeCardChartPoint, RuntimeCardChartSeries, RuntimeCardListBlock, RuntimeCardListItem, RuntimeCardMetric, RuntimeCardMetricGridBlock, RuntimeCardNativeMetadata, RuntimeCardOutcomeMetadata, RuntimeCardPreview, RuntimeCardReplyMetadata, RuntimeCardReplyStatus, RuntimeCardRequestMetadata, RuntimeCardResolutionStatus, RuntimeCardSchemaV1, RuntimeCardSummaryBlock, RuntimeCardTableBlock, RuntimeCardTone, RuntimeCardV1, RuntimeInputAnswers, RuntimeInputChoice, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputOutcomeMetadata, RuntimeInputQuestion, RuntimeInputReplyMetadata, RuntimeInputReplyStatus, RuntimeInputRequestMetadata, RuntimeInputResolutionStatus, RuntimeQuestionDefinition, RuntimeQuestionOption, } from './runtime-cards.js';
 export { DEFAULT_TURN_TRAIL_MAX_BLOCKS, DEFAULT_TURN_TRAIL_METADATA_BUDGET_BYTES, buildBoundedTurnTrail, } from './turn-output-controller.js';
 export type { BuildBoundedTurnTrailOptions, TurnOutputBlockInput, } from './turn-output-controller.js';

package/dist/browser.js

@@ -11,5 +11,5 @@ export { buildParticipationHistorySnapshot, buildParticipationHistorySnapshots,
 export { DEFAULT_RUNTIME_CAPABILITIES, ACTIVE_TURN_STALE_THRESHOLD_MS, FINAL_MESSAGE_HANDOFF_MS, WAITING_INPUT_STALE_THRESHOLD_MS, getTurnStateStaleThresholdMs, isTurnOpen, isTurnStateStale, normalizeTurnMetadata, normalizeTurnState, resolveTurnMessageSemantics, shouldPromoteConversationMessage, shouldTriggerAgentTurn, } from './turn-protocol.js';
 export { buildApprovalReply, buildApprovalRequest, buildApprovalOutcome, generateApprovalId, redactSecrets, } from './approval-format.js';
 export { DEFAULT_APPROVAL_CONFIG, parseApprovalRequestMetadata, parseApprovalReplyMetadata, parseSessionRule, } from './approval-types.js';
-export { buildRuntimeInputOutcome, buildRuntimeInputReply, buildRuntimeInputRequest, buildPlanApprovalReply, buildPlanApprovalRequest, buildQuestionReply, buildQuestionRequest, parseRuntimeInputOutcomeMetadata, parseRuntimeInputReplyMetadata, parseRuntimeInputRequestMetadata, } from './runtime-cards.js';
+export { RUNTIME_CARD_SCHEMA_V1, buildRuntimeCardOutcome, buildRuntimeCardPreview, buildRuntimeCardReply, buildRuntimeCardRequest, buildRuntimeInputOutcome, buildRuntimeInputReply, buildRuntimeInputRequest, buildPlanApprovalReply, buildPlanApprovalRequest, buildQuestionReply, buildQuestionRequest, parseRuntimeCardOutcomeMetadata, parseRuntimeCardReplyMetadata, parseRuntimeCardRequestMetadata, parseRuntimeCardV1, parseRuntimeInputOutcomeMetadata, parseRuntimeInputReplyMetadata, parseRuntimeInputRequestMetadata, } from './runtime-cards.js';
 export { DEFAULT_TURN_TRAIL_MAX_BLOCKS, DEFAULT_TURN_TRAIL_METADATA_BUDGET_BYTES, buildBoundedTurnTrail, } from './turn-output-controller.js';

package/dist/client.d.ts

@@ -1,7 +1,7 @@
 import { type CanonMessage, type CanonConversation, type CanonContact, type CanonContactRequest, type CanonMessagesPage, type CanonResolveAdmissionResult, type AgentContext, type AddMemberResult, type CreateContactRequestResult, type MediaAttachment, type SendMessageOptions, type CreateConversationOptions, type RegistrationStatus, type SetRuntimeTurnOptions, type SetStreamingOptions } from './types.js';
 import type { RuntimeInputKind } from './runtime-cards.js';
 import type { ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRisk, SessionRule } from './approval-types.js';
-import type { RuntimeInputAnswers, RuntimeInputChoice, RuntimeInputNativeMetadata, RuntimeInputQuestion } from './runtime-cards.js';
+import type { RuntimeInputAnswers, RuntimeInputChoice, RuntimeInputNativeMetadata, RuntimeInputQuestion, RuntimeCardNativeMetadata, RuntimeCardV1 } from './runtime-cards.js';
 import type { SendContextualMessageOptions, SendContextualMessageResult } from './self-context.js';
 import type { InboundDisposition } from './turn-protocol.js';
 /**
@@ -141,6 +141,44 @@ export declare class CanonClient {
         status: 'timeout';
         approvalId: string;
     }>;
+    createRuntimeCardRequest(options: {
+        conversationId: string;
+        card: RuntimeCardV1;
+        cardId?: string;
+        expiresAt?: number;
+        responseUserId?: string;
+        runtimeId?: string;
+        turnId?: string;
+        native?: RuntimeCardNativeMetadata;
+    }): Promise<{
+        success: true;
+        cardId: string;
+        messageId: string;
+        /** True when the card has actions and a response is pending; false for display cards. */
+        interactive: boolean;
+        /** Present only for interactive cards. */
+        expiresAt?: number;
+    }>;
+    consumeRuntimeCardResponse(options: {
+        conversationId: string;
+        cardId: string;
+        cancel?: boolean;
+    }): Promise<{
+        status: 'pending';
+        cardId: string;
+        expiresAt?: number;
+    } | {
+        status: 'submitted';
+        cardId: string;
+        actionId?: string;
+        values?: Record<string, unknown>;
+    } | {
+        status: 'cancelled';
+        cardId: string;
+    } | {
+        status: 'timeout';
+        cardId: string;
+    }>;
     updateRuntimeStatus(options: {
         runtime: string;
         hostMode?: boolean;

package/dist/client.js

@@ -368,6 +368,26 @@ export class CanonClient {
             throw new CanonApiError(res.status, await res.text());
         return res.json();
     }
+    async createRuntimeCardRequest(options) {
+        const res = await fetch(`${this.baseUrl}/runtime-card/request`, {
+            method: 'POST',
+            headers: this.authHeaders(),
+            body: JSON.stringify(options),
+        });
+        if (!res.ok)
+            throw new CanonApiError(res.status, await res.text());
+        return res.json();
+    }
+    async consumeRuntimeCardResponse(options) {
+        const res = await fetch(`${this.baseUrl}/runtime-card/consume`, {
+            method: 'POST',
+            headers: this.authHeaders(),
+            body: JSON.stringify(options),
+        });
+        if (!res.ok)
+            throw new CanonApiError(res.status, await res.text());
+        return res.json();
+    }
     async updateRuntimeStatus(options) {
         const res = await fetch(`${this.baseUrl}/runtime/status`, {
             method: 'POST',

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { AGENT_CAPABILITIES, CLAUDE_PERMISSION_MODE_OPTIONS, } from './types.js';
-export type { AddMemberResult, AgentCapabilities, AgentClientType, CanonControlAvailability, CanonControlDescriptor, CanonControlLiveBehavior, CanonControlSelectionPolicy, CanonControlValue, CanonContact, CanonContactRequest, CanonContactRequestStatus, CanonGroupContext, CanonGroupContextMode, CanonKnownRecentParticipant, CanonMembershipChange, CanonResolveAdmissionResult, ConversationUpdatedPayload, ContactAddedPayload, ContactApprovedPayload, ContactCardPayload, ContactRemovedPayload, ContactRequestPayload, ContactSource, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonMessage, CanonRuntimeProvenance, CanonConversation, CanonMessagesPage, CreateContactRequestResult, AgentContext, CanonStreamEvent, AgentSessionSnapshot, ResolvedAdmission, MediaAttachment, MediaAttachmentKind, MessageCreatedPayload, TypingPayload, PresencePayload, RuntimeUpdatedPayload, TurnUpdatedPayload, SendMessageOptions, CreateConversationOptions, RegistrationInput, RegistrationResult, RegistrationStatus, SetRuntimeTurnOptions, StreamingStatus, SetStreamingOptions, SessionControl, SessionState, SessionConfig, AgentRuntime, CanonRuntimeDescriptor, CanonRuntimeActionAvailability, CanonRuntimeActionCategory, CanonRuntimeActionDescriptor, CanonRuntimeActionDispatch, CanonRuntimeActionPlacement, CanonRuntimeCommandArgumentChoice, CanonRuntimeCommandArgumentDescriptor, CanonRuntimeCommandArgumentKind, CanonRuntimeCommandDescriptor, CanonRuntimeDetailTier, CanonRuntimeExecutionMetadata, CanonRuntimePresentationField, CanonRuntimePresentationHint, CanonRuntimePresentationPolicy, CanonRuntimePresentationPreset, CanonRuntimeVisibility, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeFact, CanonRuntimeFactGroup, CanonRuntimeInventory, CanonRuntimeInventoryEntry, CanonRuntimePrimitiveId, CanonRuntimeStreamingMode, CanonRuntimeStatusItem, CanonRuntimeSurfaceMode, CanonWorkspaceRootMetadata, ModelOption, PermissionModeOption, RuntimeInfoPayload, RuntimeControlError, RuntimeControlState, RuntimeControlValueSource, TurnOutputBlock, TurnOutputBlockKind, TurnOutputBlockStatus, WorkspaceOption, WorkspaceOptionSource, } from './types.js';
+export type { AddMemberResult, AgentCapabilities, AgentClientType, CanonControlAvailability, CanonControlDescriptor, CanonControlLiveBehavior, CanonControlSelectionPolicy, CanonControlValue, CanonRuntimeCardCapabilities, CanonRuntimeRichCardCapability, CanonContact, CanonContactRequest, CanonContactRequestStatus, CanonGroupContext, CanonGroupContextMode, CanonKnownRecentParticipant, CanonMembershipChange, CanonResolveAdmissionResult, ConversationUpdatedPayload, ContactAddedPayload, ContactApprovedPayload, ContactCardPayload, ContactRemovedPayload, ContactRequestPayload, ContactSource, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonMessage, CanonRuntimeProvenance, CanonConversation, CanonMessagesPage, CreateContactRequestResult, AgentContext, CanonStreamEvent, AgentSessionSnapshot, ResolvedAdmission, MediaAttachment, MediaAttachmentKind, MessageCreatedPayload, TypingPayload, PresencePayload, RuntimeUpdatedPayload, TurnUpdatedPayload, SendMessageOptions, CreateConversationOptions, RegistrationInput, RegistrationResult, RegistrationStatus, SetRuntimeTurnOptions, StreamingStatus, SetStreamingOptions, SessionControl, SessionState, SessionConfig, AgentRuntime, CanonRuntimeDescriptor, CanonRuntimeActionAvailability, CanonRuntimeActionCategory, CanonRuntimeActionDescriptor, CanonRuntimeActionDispatch, CanonRuntimeActionPlacement, CanonRuntimeCommandArgumentChoice, CanonRuntimeCommandArgumentDescriptor, CanonRuntimeCommandArgumentKind, CanonRuntimeCommandDescriptor, CanonRuntimeDetailTier, CanonRuntimeExecutionMetadata, CanonRuntimePresentationField, CanonRuntimePresentationHint, CanonRuntimePresentationPolicy, CanonRuntimePresentationPreset, CanonRuntimeVisibility, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeFact, CanonRuntimeFactGroup, CanonRuntimeInventory, CanonRuntimeInventoryEntry, CanonRuntimePrimitiveId, CanonRuntimeStreamingMode, CanonRuntimeStatusItem, CanonRuntimeSurfaceMode, CanonWorkspaceRootMetadata, ModelOption, PermissionModeOption, RuntimeInfoPayload, RuntimeControlError, RuntimeControlState, RuntimeControlValueSource, TurnOutputBlock, TurnOutputBlockKind, TurnOutputBlockStatus, WorkspaceOption, WorkspaceOptionSource, } from './types.js';
 export { DEFAULT_FIRST_PARTY_RUNTIME_PRESENTATION, RUNTIME_PRESENTATION_FIELDS, buildRuntimePresentationPolicy, getRuntimePresentationHint, isRuntimePresentationField, isRuntimePresentationFieldHidden, redactAgentRuntimeForConversation, redactAgentSessionSnapshotForConversation, redactExecutionMetadataForConversation, redactRuntimeActivityItemForConversation, redactRuntimeDescriptorForConversation, redactRuntimeInfoForConversation, redactSessionStateForConversation, } from './runtime-presentation.js';
 export { buildRuntimeProvenance, resolveRuntimeProvenance, } from './provenance.js';
 export type { CanonSelfContext, CanonSelfContextType, SelfContextPromptRenderOptions, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, } from './self-context.js';
@@ -20,8 +20,8 @@ export { ApprovalManager } from './approval-manager.js';
 export { generateApprovalId, buildApprovalRequest, buildApprovalReply, buildApprovalOutcome, redactSecrets, } from './approval-format.js';
 export { DEFAULT_APPROVAL_CONFIG, parseApprovalRequestMetadata, parseApprovalReplyMetadata, parseSessionRule, } from './approval-types.js';
 export type { ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalNativeRequestMetadata, ApprovalRisk, ApprovalReplyMetadata, ApprovalOutcomeMetadata, SessionRule, ApprovalResult, ApprovalConfig, } from './approval-types.js';
-export { buildRuntimeInputOutcome, buildRuntimeInputReply, buildRuntimeInputRequest, buildPlanApprovalReply, buildPlanApprovalRequest, buildQuestionReply, buildQuestionRequest, parseRuntimeInputOutcomeMetadata, parseRuntimeInputReplyMetadata, parseRuntimeInputRequestMetadata, } from './runtime-cards.js';
-export type { ClaudeQuestionMetadata, ClaudeQuestionReplyMetadata, PlanApprovalMetadata, PlanApprovalReplyMetadata, RuntimeInputAnswers, RuntimeInputChoice, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputOutcomeMetadata, RuntimeInputQuestion, RuntimeInputReplyMetadata, RuntimeInputReplyStatus, RuntimeInputRequestMetadata, RuntimeInputResolutionStatus, RuntimeQuestionDefinition, RuntimeQuestionOption, } from './runtime-cards.js';
+export { RUNTIME_CARD_SCHEMA_V1, buildRuntimeCardOutcome, buildRuntimeCardPreview, buildRuntimeCardReply, buildRuntimeCardRequest, buildRuntimeInputOutcome, buildRuntimeInputReply, buildRuntimeInputRequest, buildPlanApprovalReply, buildPlanApprovalRequest, buildQuestionReply, buildQuestionRequest, parseRuntimeCardOutcomeMetadata, parseRuntimeCardReplyMetadata, parseRuntimeCardRequestMetadata, parseRuntimeCardV1, parseRuntimeInputOutcomeMetadata, parseRuntimeInputReplyMetadata, parseRuntimeInputRequestMetadata, } from './runtime-cards.js';
+export type { ClaudeQuestionMetadata, ClaudeQuestionReplyMetadata, PlanApprovalMetadata, PlanApprovalReplyMetadata, RuntimeCardAction, RuntimeCardActionsBlock, RuntimeCardBlock, RuntimeCardBlockKind, RuntimeCardCalloutBlock, RuntimeCardChartBlock, RuntimeCardChartPoint, RuntimeCardChartSeries, RuntimeCardListBlock, RuntimeCardListItem, RuntimeCardMetric, RuntimeCardMetricGridBlock, RuntimeCardNativeMetadata, RuntimeCardOutcomeMetadata, RuntimeCardPreview, RuntimeCardReplyMetadata, RuntimeCardReplyStatus, RuntimeCardRequestMetadata, RuntimeCardResolutionStatus, RuntimeCardSchemaV1, RuntimeCardSummaryBlock, RuntimeCardTableBlock, RuntimeCardTone, RuntimeCardV1, RuntimeInputAnswers, RuntimeInputChoice, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputOutcomeMetadata, RuntimeInputQuestion, RuntimeInputReplyMetadata, RuntimeInputReplyStatus, RuntimeInputRequestMetadata, RuntimeInputResolutionStatus, RuntimeQuestionDefinition, RuntimeQuestionOption, } from './runtime-cards.js';
 export { createStreamingHelper } from './streaming.js';
 export type { RTDBHandle, RTDBRef, ServerTimestamp, StreamingHelperOptions, StreamingNode } from './streaming.js';
 export { DEFAULT_TURN_TRAIL_MAX_BLOCKS, DEFAULT_TURN_TRAIL_METADATA_BUDGET_BYTES, buildBoundedTurnTrail, createTurnOutputController, } from './turn-output-controller.js';

package/dist/index.js

@@ -19,7 +19,7 @@ export { ackRegistrationApproval, registerAndWaitForApproval, submitRegistration
 export { ApprovalManager } from './approval-manager.js';
 export { generateApprovalId, buildApprovalRequest, buildApprovalReply, buildApprovalOutcome, redactSecrets, } from './approval-format.js';
 export { DEFAULT_APPROVAL_CONFIG, parseApprovalRequestMetadata, parseApprovalReplyMetadata, parseSessionRule, } from './approval-types.js';
-export { buildRuntimeInputOutcome, buildRuntimeInputReply, buildRuntimeInputRequest, buildPlanApprovalReply, buildPlanApprovalRequest, buildQuestionReply, buildQuestionRequest, parseRuntimeInputOutcomeMetadata, parseRuntimeInputReplyMetadata, parseRuntimeInputRequestMetadata, } from './runtime-cards.js';
+export { RUNTIME_CARD_SCHEMA_V1, buildRuntimeCardOutcome, buildRuntimeCardPreview, buildRuntimeCardReply, buildRuntimeCardRequest, buildRuntimeInputOutcome, buildRuntimeInputReply, buildRuntimeInputRequest, buildPlanApprovalReply, buildPlanApprovalRequest, buildQuestionReply, buildQuestionRequest, parseRuntimeCardOutcomeMetadata, parseRuntimeCardReplyMetadata, parseRuntimeCardRequestMetadata, parseRuntimeCardV1, parseRuntimeInputOutcomeMetadata, parseRuntimeInputReplyMetadata, parseRuntimeInputRequestMetadata, } from './runtime-cards.js';
 // Streaming (RTDB helpers)
 export { createStreamingHelper } from './streaming.js';
 export { DEFAULT_TURN_TRAIL_MAX_BLOCKS, DEFAULT_TURN_TRAIL_METADATA_BUDGET_BYTES, buildBoundedTurnTrail, createTurnOutputController, } from './turn-output-controller.js';

package/dist/runtime-cards.d.ts

@@ -98,6 +98,138 @@ export interface RuntimeInputOutcomeMetadata {
     status: RuntimeInputResolutionStatus;
     reason?: 'submitted' | 'cancelled' | 'timeout' | 'expired' | 'interrupted';
 }
+export declare const RUNTIME_CARD_SCHEMA_V1: "canon.card.v1";
+export declare const RUNTIME_CARD_PUBLIC_REQUEST_TEXT: "Action requested";
+export type RuntimeCardSchemaV1 = typeof RUNTIME_CARD_SCHEMA_V1;
+export type RuntimeCardBlockKind = 'summary' | 'metricGrid' | 'chart' | 'table' | 'list' | 'callout' | 'actions';
+export type RuntimeCardTone = 'neutral' | 'primary' | 'positive' | 'warning' | 'negative' | 'danger' | 'critical' | 'welcome';
+export type RuntimeCardReplyStatus = 'submitted' | 'cancelled';
+export type RuntimeCardResolutionStatus = RuntimeCardReplyStatus | 'timeout';
+export interface RuntimeCardSummaryBlock {
+    kind: 'summary';
+    title?: string;
+    text: string;
+}
+export interface RuntimeCardMetric {
+    label: string;
+    value: string;
+    delta?: string;
+    tone?: RuntimeCardTone;
+}
+export interface RuntimeCardMetricGridBlock {
+    kind: 'metricGrid';
+    title?: string;
+    metrics: RuntimeCardMetric[];
+}
+export interface RuntimeCardChartPoint {
+    x: string;
+    y: number;
+}
+export interface RuntimeCardChartSeries {
+    name?: string;
+    points: RuntimeCardChartPoint[];
+}
+export interface RuntimeCardChartBlock {
+    kind: 'chart';
+    chart: 'line' | 'bar';
+    title?: string;
+    yLabel?: string;
+    series: RuntimeCardChartSeries[];
+}
+export interface RuntimeCardTableBlock {
+    kind: 'table';
+    title?: string;
+    columns: string[];
+    rows: string[][];
+}
+export interface RuntimeCardListItem {
+    label: string;
+    detail?: string;
+    status?: 'pending' | 'done' | 'blocked' | 'warning';
+}
+export interface RuntimeCardListBlock {
+    kind: 'list';
+    title?: string;
+    items: RuntimeCardListItem[];
+}
+export interface RuntimeCardCalloutBlock {
+    kind: 'callout';
+    title?: string;
+    text: string;
+    tone?: RuntimeCardTone;
+}
+export interface RuntimeCardAction {
+    id: string;
+    label: string;
+    tone?: RuntimeCardTone;
+}
+export interface RuntimeCardActionsBlock {
+    kind: 'actions';
+    title?: string;
+    actions: RuntimeCardAction[];
+}
+export type RuntimeCardBlock = RuntimeCardSummaryBlock | RuntimeCardMetricGridBlock | RuntimeCardChartBlock | RuntimeCardTableBlock | RuntimeCardListBlock | RuntimeCardCalloutBlock | RuntimeCardActionsBlock;
+export interface RuntimeCardV1 {
+    schema: RuntimeCardSchemaV1;
+    cardId?: string;
+    template?: string;
+    tone?: RuntimeCardTone;
+    title: string;
+    fallbackText: string;
+    blocks: RuntimeCardBlock[];
+}
+export interface RuntimeCardPreview {
+    title?: string;
+    tone?: RuntimeCardTone;
+    template?: string;
+    blockKinds: RuntimeCardBlockKind[];
+}
+export interface RuntimeCardNativeMetadata {
+    runtime?: string;
+    method?: string;
+    requestId?: string;
+    sessionKey?: string;
+    turnId?: string;
+    handles?: Record<string, string>;
+}
+export interface RuntimeCardRequestMetadata {
+    type: 'runtime_card_request';
+    cardId: string;
+    cardKind: string;
+    schemaVersion: RuntimeCardSchemaV1;
+    fallbackText: string;
+    responseUserId?: string;
+    expiresAt: string;
+    runtimeId?: string;
+    turnId?: string;
+    native?: RuntimeCardNativeMetadata;
+    /** True when the card carries an actions block (the agent waits for a
+     *  response); false/absent for display/report cards shown to all members. */
+    interactive?: boolean;
+    cardPreview: RuntimeCardPreview;
+    turnSemantics: 'control';
+    replyBehavior: 'suppress_auto_reply';
+}
+export interface RuntimeCardReplyMetadata {
+    type: 'runtime_card_reply';
+    cardId: string;
+    status: RuntimeCardReplyStatus;
+    actionId?: string;
+    answerSummary?: string;
+    sensitive?: boolean;
+    turnSemantics: 'control';
+    replyBehavior: 'suppress_auto_reply';
+}
+export interface RuntimeCardOutcomeMetadata {
+    type: 'runtime_card_outcome';
+    cardId: string;
+    status: RuntimeCardResolutionStatus;
+    reason?: 'submitted' | 'cancelled' | 'timeout' | 'expired' | 'interrupted';
+    turnSemantics: 'control';
+    replyBehavior: 'suppress_auto_reply';
+}
+export declare function parseRuntimeCardV1(value: unknown): RuntimeCardV1 | null;
+export declare function buildRuntimeCardPreview(card: RuntimeCardV1): RuntimeCardPreview;
 export declare function buildQuestionRequest(questionId: string, questions: RuntimeQuestionDefinition[], options?: {
     responseUserId?: string;
 }): {
@@ -136,6 +268,34 @@ export declare function buildRuntimeInputOutcome(inputId: string, status: Runtim
     text: string;
     metadata: RuntimeInputOutcomeMetadata;
 };
+export declare function buildRuntimeCardRequest(card: RuntimeCardV1, input: {
+    cardId?: string;
+    responseUserId?: string;
+    expiresAt: string | number | Date;
+    runtimeId?: string;
+    turnId?: string;
+    native?: RuntimeCardNativeMetadata;
+}): {
+    text: string;
+    metadata: RuntimeCardRequestMetadata;
+};
+export declare function buildRuntimeCardReply(cardId: string, status: RuntimeCardReplyStatus, details?: {
+    actionId?: string;
+    answerSummary?: string;
+    sensitive?: boolean;
+}): {
+    text: string;
+    metadata: RuntimeCardReplyMetadata;
+};
+export declare function buildRuntimeCardOutcome(cardId: string, status: RuntimeCardResolutionStatus, details?: {
+    reason?: RuntimeCardOutcomeMetadata['reason'];
+}): {
+    text: string;
+    metadata: RuntimeCardOutcomeMetadata;
+};
 export declare function parseRuntimeInputRequestMetadata(value: unknown): RuntimeInputRequestMetadata | null;
+export declare function parseRuntimeCardRequestMetadata(value: unknown): RuntimeCardRequestMetadata | null;
+export declare function parseRuntimeCardReplyMetadata(value: unknown): RuntimeCardReplyMetadata | null;
+export declare function parseRuntimeCardOutcomeMetadata(value: unknown): RuntimeCardOutcomeMetadata | null;
 export declare function parseRuntimeInputReplyMetadata(value: unknown): RuntimeInputReplyMetadata | null;
 export declare function parseRuntimeInputOutcomeMetadata(value: unknown): RuntimeInputOutcomeMetadata | null;

package/dist/runtime-cards.js

@@ -1,3 +1,5 @@
+export const RUNTIME_CARD_SCHEMA_V1 = 'canon.card.v1';
+export const RUNTIME_CARD_PUBLIC_REQUEST_TEXT = 'Action requested';
 function isRecord(value) {
     return Boolean(value && typeof value === 'object' && !Array.isArray(value));
 }
@@ -85,6 +87,223 @@ function normalizeRuntimeInputNative(value) {
     }
     return Object.keys(native).length > 0 ? native : undefined;
 }
+function normalizeRuntimeCardTone(value) {
+    return value === 'neutral'
+        || value === 'primary'
+        || value === 'positive'
+        || value === 'warning'
+        || value === 'negative'
+        || value === 'danger'
+        || value === 'critical'
+        || value === 'welcome'
+        ? value
+        : undefined;
+}
+function normalizeRuntimeCardBlockKind(value) {
+    return value === 'summary'
+        || value === 'metricGrid'
+        || value === 'chart'
+        || value === 'table'
+        || value === 'list'
+        || value === 'callout'
+        || value === 'actions'
+        ? value
+        : null;
+}
+function normalizeRuntimeCardActionId(value) {
+    const normalized = normalizeString(value, 80);
+    return normalized && /^[A-Za-z0-9_.:-]{1,80}$/.test(normalized) ? normalized : null;
+}
+function cardText(value) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    return trimmed ? trimmed : null;
+}
+// Lenient structural parse: shape and required-field checks only — no numeric
+// caps, no length caps, and unknown extra keys are tolerated for
+// forward-compatibility. Strict business caps (<=6 series, <=24 rows, single
+// actions block, deduped action ids, etc.) live in @canonmsg/rich-cards
+// `validateCard()` and run agent-side before send; the backend additionally
+// bounds total card size and block count at the transport envelope.
+function normalizeRuntimeCardStringArray(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        return null;
+    const out = value.flatMap((entry) => {
+        const normalized = cardText(entry);
+        return normalized ? [normalized] : [];
+    });
+    return out.length === value.length ? out : null;
+}
+function normalizeRuntimeCardMetrics(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        return null;
+    const metrics = value.flatMap((entry) => {
+        if (!isRecord(entry))
+            return [];
+        const label = cardText(entry.label);
+        const metricValue = cardText(entry.value);
+        if (!label || !metricValue)
+            return [];
+        const delta = cardText(entry.delta) ?? undefined;
+        const tone = normalizeRuntimeCardTone(entry.tone);
+        return [{
+                label,
+                value: metricValue,
+                ...(delta ? { delta } : {}),
+                ...(tone ? { tone } : {}),
+            }];
+    });
+    return metrics.length === value.length ? metrics : null;
+}
+function normalizeRuntimeCardSeries(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        return null;
+    const series = value.flatMap((entry) => {
+        if (!isRecord(entry) || !Array.isArray(entry.points) || entry.points.length === 0)
+            return [];
+        const points = entry.points.flatMap((point) => {
+            if (!isRecord(point))
+                return [];
+            const x = cardText(point.x);
+            const y = typeof point.y === 'number' && Number.isFinite(point.y) ? point.y : null;
+            return x && y !== null ? [{ x, y }] : [];
+        });
+        if (points.length !== entry.points.length)
+            return [];
+        const name = cardText(entry.name) ?? undefined;
+        return [{ ...(name ? { name } : {}), points }];
+    });
+    return series.length === value.length ? series : null;
+}
+function normalizeRuntimeCardRows(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        return null;
+    const rows = value.flatMap((entry) => {
+        const cells = normalizeRuntimeCardStringArray(entry);
+        return cells ? [cells] : [];
+    });
+    return rows.length === value.length ? rows : null;
+}
+function normalizeRuntimeCardListItems(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        return null;
+    const items = value.flatMap((entry) => {
+        if (!isRecord(entry))
+            return [];
+        const label = cardText(entry.label);
+        if (!label)
+            return [];
+        const detail = cardText(entry.detail) ?? undefined;
+        const status = entry.status === 'pending'
+            || entry.status === 'done'
+            || entry.status === 'blocked'
+            || entry.status === 'warning'
+            ? entry.status
+            : undefined;
+        return [{ label, ...(detail ? { detail } : {}), ...(status ? { status } : {}) }];
+    });
+    return items.length === value.length ? items : null;
+}
+function normalizeRuntimeCardActions(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        return null;
+    const actions = value.flatMap((entry) => {
+        if (!isRecord(entry))
+            return [];
+        const id = normalizeRuntimeCardActionId(entry.id);
+        const label = cardText(entry.label);
+        if (!id || !label)
+            return [];
+        const tone = normalizeRuntimeCardTone(entry.tone);
+        return [{ id, label, ...(tone ? { tone } : {}) }];
+    });
+    return actions.length === value.length ? actions : null;
+}
+function normalizeRuntimeCardBlocks(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        return null;
+    const blocks = value.flatMap((entry) => {
+        if (!isRecord(entry))
+            return [];
+        const kind = normalizeRuntimeCardBlockKind(entry.kind);
+        if (!kind)
+            return [];
+        const title = cardText(entry.title) ?? undefined;
+        if (kind === 'summary') {
+            const text = cardText(entry.text);
+            return text ? [{ kind, ...(title ? { title } : {}), text }] : [];
+        }
+        if (kind === 'metricGrid') {
+            const metrics = normalizeRuntimeCardMetrics(entry.metrics);
+            return metrics ? [{ kind, ...(title ? { title } : {}), metrics }] : [];
+        }
+        if (kind === 'chart') {
+            const chart = entry.chart === 'line' || entry.chart === 'bar' ? entry.chart : null;
+            const series = normalizeRuntimeCardSeries(entry.series);
+            const yLabel = cardText(entry.yLabel) ?? undefined;
+            return chart && series ? [{ kind, chart, ...(title ? { title } : {}), ...(yLabel ? { yLabel } : {}), series }] : [];
+        }
+        if (kind === 'table') {
+            const columns = normalizeRuntimeCardStringArray(entry.columns);
+            const rows = normalizeRuntimeCardRows(entry.rows);
+            return columns && rows ? [{ kind, ...(title ? { title } : {}), columns, rows }] : [];
+        }
+        if (kind === 'list') {
+            const items = normalizeRuntimeCardListItems(entry.items);
+            return items ? [{ kind, ...(title ? { title } : {}), items }] : [];
+        }
+        if (kind === 'callout') {
+            const text = cardText(entry.text);
+            const tone = normalizeRuntimeCardTone(entry.tone);
+            return text ? [{ kind, ...(title ? { title } : {}), text, ...(tone ? { tone } : {}) }] : [];
+        }
+        const actions = normalizeRuntimeCardActions(entry.actions);
+        return actions ? [{ kind, ...(title ? { title } : {}), actions }] : [];
+    });
+    return blocks.length === value.length && blocks.length > 0 ? blocks : null;
+}
+function normalizeRuntimeCardNative(value) {
+    const native = normalizeRuntimeInputNative(value);
+    return native;
+}
+function assertNoSensitiveRuntimeCardPayload(value) {
+    return !('value' in value)
+        && !('values' in value)
+        && !('answer' in value)
+        && !('answers' in value)
+        && !('password' in value)
+        && !('secret' in value)
+        && !('rawValue' in value);
+}
+export function parseRuntimeCardV1(value) {
+    if (!isRecord(value) || value.schema !== RUNTIME_CARD_SCHEMA_V1)
+        return null;
+    const title = cardText(value.title);
+    const fallbackText = cardText(value.fallbackText);
+    const blocks = normalizeRuntimeCardBlocks(value.blocks);
+    if (!title || !fallbackText || !blocks)
+        return null;
+    const cardId = normalizeRuntimeCardActionId(value.cardId) ?? undefined;
+    const template = cardText(value.template) ?? undefined;
+    const tone = normalizeRuntimeCardTone(value.tone);
+    return {
+        schema: RUNTIME_CARD_SCHEMA_V1,
+        ...(cardId ? { cardId } : {}),
+        ...(template ? { template } : {}),
+        ...(tone ? { tone } : {}),
+        title,
+        fallbackText,
+        blocks,
+    };
+}
+export function buildRuntimeCardPreview(card) {
+    const hasActions = card.blocks.some((block) => block.kind === 'actions');
+    return {
+        title: hasActions ? 'Action requested' : 'Runtime card',
+        blockKinds: card.blocks.map((block) => block.kind).slice(0, 12),
+    };
+}
 function assertNoSensitiveRuntimeInputPayload(value) {
     return !('value' in value)
         && !('answer' in value)
@@ -194,6 +413,65 @@ export function buildRuntimeInputOutcome(inputId, status, details) {
         },
     };
 }
+export function buildRuntimeCardRequest(card, input) {
+    const parsed = parseRuntimeCardV1(card);
+    if (!parsed) {
+        throw new Error('Invalid runtime card document');
+    }
+    const cardId = normalizeRuntimeCardActionId(input.cardId ?? parsed.cardId) ?? `card_${Date.now().toString(36)}`;
+    const expiresAt = input.expiresAt instanceof Date
+        ? input.expiresAt.toISOString()
+        : typeof input.expiresAt === 'number'
+            ? new Date(input.expiresAt).toISOString()
+            : new Date(Date.parse(input.expiresAt)).toISOString();
+    return {
+        text: RUNTIME_CARD_PUBLIC_REQUEST_TEXT,
+        metadata: {
+            type: 'runtime_card_request',
+            cardId,
+            cardKind: 'runtime_card',
+            schemaVersion: RUNTIME_CARD_SCHEMA_V1,
+            fallbackText: RUNTIME_CARD_PUBLIC_REQUEST_TEXT,
+            ...(input.responseUserId ? { responseUserId: input.responseUserId.slice(0, 128) } : {}),
+            expiresAt,
+            ...(input.runtimeId ? { runtimeId: input.runtimeId.slice(0, 128) } : {}),
+            ...(input.turnId ? { turnId: input.turnId.slice(0, 128) } : {}),
+            cardPreview: buildRuntimeCardPreview(parsed),
+            turnSemantics: 'control',
+            replyBehavior: 'suppress_auto_reply',
+        },
+    };
+}
+export function buildRuntimeCardReply(cardId, status, details) {
+    return {
+        text: status === 'submitted' ? 'Submitted' : 'Cancelled',
+        metadata: {
+            type: 'runtime_card_reply',
+            cardId,
+            status,
+            ...(details?.sensitive ? { sensitive: true } : {}),
+            turnSemantics: 'control',
+            replyBehavior: 'suppress_auto_reply',
+        },
+    };
+}
+export function buildRuntimeCardOutcome(cardId, status, details) {
+    return {
+        text: status === 'timeout'
+            ? 'Card request expired'
+            : status === 'cancelled'
+                ? 'Card request cancelled'
+                : 'Card request resolved',
+        metadata: {
+            type: 'runtime_card_outcome',
+            cardId,
+            status,
+            ...(details?.reason ? { reason: details.reason } : {}),
+            turnSemantics: 'control',
+            replyBehavior: 'suppress_auto_reply',
+        },
+    };
+}
 export function parseRuntimeInputRequestMetadata(value) {
     if (!isRecord(value) || value.type !== 'runtime_input_request')
         return null;
@@ -229,6 +507,105 @@ export function parseRuntimeInputRequestMetadata(value) {
         ...(value.sensitive === true ? { sensitive: true } : {}),
     };
 }
+function normalizeRuntimeCardPreview(value) {
+    if (!isRecord(value))
+        return null;
+    const blockKinds = Array.isArray(value.blockKinds)
+        ? value.blockKinds.slice(0, 12).flatMap((entry) => {
+            const kind = normalizeRuntimeCardBlockKind(entry);
+            return kind ? [kind] : [];
+        })
+        : [];
+    return {
+        ...(normalizeString(value.title, 120) ? { title: normalizeString(value.title, 120) } : {}),
+        ...(normalizeRuntimeCardTone(value.tone) ? { tone: normalizeRuntimeCardTone(value.tone) } : {}),
+        ...(normalizeString(value.template, 120) ? { template: normalizeString(value.template, 120) } : {}),
+        blockKinds,
+    };
+}
+export function parseRuntimeCardRequestMetadata(value) {
+    if (!isRecord(value) || value.type !== 'runtime_card_request')
+        return null;
+    if (!assertNoSensitiveRuntimeCardPayload(value))
+        return null;
+    const cardId = normalizeRuntimeCardActionId(value.cardId);
+    const cardKind = normalizeString(value.cardKind, 120);
+    const fallbackText = normalizeString(value.fallbackText, 500);
+    const responseUserId = normalizeString(value.responseUserId, 128) ?? undefined;
+    const expiresAtRaw = normalizeString(value.expiresAt, 128);
+    const expiresMs = expiresAtRaw ? Date.parse(expiresAtRaw) : NaN;
+    const cardPreview = normalizeRuntimeCardPreview(value.cardPreview);
+    if (!cardId || !cardKind || value.schemaVersion !== RUNTIME_CARD_SCHEMA_V1 || !fallbackText || !Number.isFinite(expiresMs) || !cardPreview) {
+        return null;
+    }
+    const runtimeId = normalizeString(value.runtimeId, 128) ?? undefined;
+    const turnId = normalizeString(value.turnId, 128) ?? undefined;
+    const native = normalizeRuntimeCardNative(value.native);
+    return {
+        type: 'runtime_card_request',
+        cardId,
+        cardKind,
+        schemaVersion: RUNTIME_CARD_SCHEMA_V1,
+        fallbackText,
+        ...(responseUserId ? { responseUserId } : {}),
+        expiresAt: new Date(expiresMs).toISOString(),
+        ...(runtimeId ? { runtimeId } : {}),
+        ...(turnId ? { turnId } : {}),
+        ...(native ? { native } : {}),
+        cardPreview,
+        turnSemantics: 'control',
+        replyBehavior: 'suppress_auto_reply',
+    };
+}
+export function parseRuntimeCardReplyMetadata(value) {
+    if (!isRecord(value) || value.type !== 'runtime_card_reply')
+        return null;
+    if (!assertNoSensitiveRuntimeCardPayload(value))
+        return null;
+    const cardId = normalizeRuntimeCardActionId(value.cardId);
+    const status = value.status === 'submitted' || value.status === 'cancelled' ? value.status : null;
+    if (!cardId || !status)
+        return null;
+    const actionId = normalizeRuntimeCardActionId(value.actionId) ?? undefined;
+    const answerSummary = value.sensitive === true ? undefined : normalizeString(value.answerSummary, 500) ?? undefined;
+    return {
+        type: 'runtime_card_reply',
+        cardId,
+        status,
+        ...(actionId ? { actionId } : {}),
+        ...(answerSummary ? { answerSummary } : {}),
+        ...(value.sensitive === true ? { sensitive: true } : {}),
+        turnSemantics: 'control',
+        replyBehavior: 'suppress_auto_reply',
+    };
+}
+export function parseRuntimeCardOutcomeMetadata(value) {
+    if (!isRecord(value) || value.type !== 'runtime_card_outcome')
+        return null;
+    if (!assertNoSensitiveRuntimeCardPayload(value))
+        return null;
+    const cardId = normalizeRuntimeCardActionId(value.cardId);
+    const status = value.status === 'submitted' || value.status === 'cancelled' || value.status === 'timeout'
+        ? value.status
+        : null;
+    if (!cardId || !status)
+        return null;
+    const reason = value.reason === 'submitted'
+        || value.reason === 'cancelled'
+        || value.reason === 'timeout'
+        || value.reason === 'expired'
+        || value.reason === 'interrupted'
+        ? value.reason
+        : undefined;
+    return {
+        type: 'runtime_card_outcome',
+        cardId,
+        status,
+        ...(reason ? { reason } : {}),
+        turnSemantics: 'control',
+        replyBehavior: 'suppress_auto_reply',
+    };
+}
 export function parseRuntimeInputReplyMetadata(value) {
     if (!isRecord(value) || value.type !== 'runtime_input_reply')
         return null;

package/dist/runtime-descriptor.d.ts

@@ -58,4 +58,5 @@ export declare function buildFirstPartyCodingRuntimeDescriptor(input: {
     streamingTextMode: CanonRuntimeStreamingMode;
     admissionActions?: HostAdmissionActionCapabilities;
     presentation?: CanonRuntimePresentationPolicy;
+    runtimeCards?: CanonRuntimeDescriptor['runtimeCards'];
 }): CanonRuntimeDescriptor;

package/dist/runtime-descriptor.js

@@ -159,5 +159,6 @@ export function buildFirstPartyCodingRuntimeDescriptor(input) {
         streamingTextMode: input.streamingTextMode,
         presentation: input.presentation ?? DEFAULT_FIRST_PARTY_RUNTIME_PRESENTATION,
         admissionActions: input.admissionActions,
+        ...(input.runtimeCards ? { runtimeCards: input.runtimeCards } : {}),
     };
 }

package/dist/turn-protocol.js

@@ -54,7 +54,9 @@ function isHiddenRuntimeCardMetadata(metadata) {
         || metadata.type === 'question_reply'
         || metadata.type === 'plan_approval_reply'
         || metadata.type === 'runtime_input_reply'
-        || metadata.type === 'runtime_input_outcome';
+        || metadata.type === 'runtime_input_outcome'
+        || metadata.type === 'runtime_card_reply'
+        || metadata.type === 'runtime_card_outcome';
 }
 export function normalizeTurnMetadata(metadata) {
     if (!isRecord(metadata))

package/dist/types.d.ts

@@ -2,6 +2,7 @@ import type { ExecutionEnvironmentMode } from './execution-environment-mode.js';
 import type { ResolvedAgentBehaviorPolicy } from './policy.js';
 import type { DeliveryIntent, RuntimeCapabilities, TurnLifecycleState } from './turn-protocol.js';
 import type { CanonSelfContext } from './self-context.js';
+import type { RuntimeCardV1 } from './runtime-cards.js';
 export type { ExecutionEnvironmentMode };
 export type MediaAttachmentKind = 'image' | 'audio' | 'file';
 export interface MediaAttachment {
@@ -54,6 +55,8 @@ export interface CanonMessage {
     forwardedFrom?: ForwardedFrom;
     metadata?: Record<string, unknown>;
     contactCard?: ContactCardPayload;
+    /** Durable canon.card.v1 runtime card content (persists in chat history). */
+    runtimeCard?: RuntimeCardV1;
     status: 'sent' | 'read';
     deleted: boolean;
     createdAt: string;
@@ -340,10 +343,23 @@ export interface CanonControlDescriptor {
     tier?: CanonRuntimeDetailTier;
     sensitive?: boolean;
 }
+export interface CanonRuntimeRichCardCapability {
+    schema: 'canon.card.v1';
+    lifecycle?: 'blocking_requires_action';
+    responder?: 'agent_owner';
+    result?: 'action_or_values';
+    maxTimeoutMs?: number;
+    blockKinds: ReadonlyArray<'summary' | 'metricGrid' | 'chart' | 'table' | 'list' | 'callout' | 'actions'>;
+    native?: boolean;
+}
+export interface CanonRuntimeCardCapabilities {
+    rich?: CanonRuntimeRichCardCapability;
+}
 export interface CanonRuntimeDescriptor {
     coreControls: ReadonlyArray<CanonControlDescriptor>;
     runtimeControls?: ReadonlyArray<CanonControlDescriptor>;
     commands?: ReadonlyArray<CanonRuntimeCommandDescriptor>;
+    runtimeCards?: CanonRuntimeCardCapabilities;
     /**
      * Optional setup-time local roots advertised by a runtime. These are
      * metadata only for now; existing session config still selects concrete

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/core",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Canon core — shared types, REST client, SSE stream, and registration for Canon messaging",
   "type": "module",
   "main": "dist/index.js",