@canonmsg/agent-sdk 2.0.0 → 2.1.0

package/dist/canon-agent.js

@@ -1,7 +1,8 @@
-import { ApprovalManager, CanonClient, buildCanonGroupContext, createTurnOutputController, createRuntimeStatePublisher, diffCanonMemberIds, FINAL_MESSAGE_HANDOFF_MS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildRuntimeInputOutcome, initRTDBAuth, rtdbRead, rtdbWrite, normalizeTurnMetadata, reachOutToCanonContact, resolveCanonReplyContext, resolveMessageActiveSelfContextId, resolveRuntimeProvenance, selectActiveSelfContexts, } from '@canonmsg/core';
+import { ApprovalManager, CanonClient, buildCanonGroupContext, createTurnOutputController, createRuntimeStatePublisher, diffCanonMemberIds, FINAL_MESSAGE_HANDOFF_MS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildRuntimeCardOutcome, buildRuntimeInputOutcome, initRTDBAuth, rtdbRead, rtdbWrite, normalizeTurnMetadata, reachOutToCanonContact, resolveCanonReplyContext, resolveMessageActiveSelfContextId, resolveRuntimeProvenance, selectActiveSelfContexts, } from '@canonmsg/core';
 import { randomUUID } from 'node:crypto';
 import { AuthManager } from './auth.js';
 import { Debouncer } from './debouncer.js';
+import { buildRuntimeCardCreateArgs } from './runtime-card.js';
 import { materializeMessageMedia, materializeReplyContextMedia, sendMediaFileMessage, uploadMediaFile, } from './media.js';
 import { SessionManager } from './session-manager.js';
 const AGENT_RUNTIME_HEARTBEAT_MS = 30_000;
@@ -23,6 +24,17 @@ const DEFAULT_SDK_RUNTIME_DESCRIPTOR = {
     runtimeControls: [],
     supportsInterrupt: false,
     streamingTextMode: 'snapshot',
+    runtimeCards: {
+        rich: {
+            schema: 'canon.card.v1',
+            lifecycle: 'blocking_requires_action',
+            responder: 'agent_owner',
+            result: 'action_or_values',
+            maxTimeoutMs: 30 * 60_000,
+            blockKinds: ['summary', 'metricGrid', 'chart', 'table', 'list', 'callout', 'actions'],
+            native: true,
+        },
+    },
 };
 const STANDARD_PRIMITIVE_COMMANDS = {
     'runtime.status': {
@@ -146,6 +158,13 @@ function safeRuntimeInputId(value, kind) {
         ? normalized
         : `${kind}_${randomUUID()}`;
 }
+function safeRuntimeCardId(value) {
+    const raw = value?.trim() || `card_${randomUUID()}`;
+    const normalized = raw.replace(/[.#$\[\]\/\s]+/g, '_').slice(0, 80);
+    return RUNTIME_INPUT_ID_PATTERN.test(normalized)
+        ? normalized
+        : `card_${randomUUID()}`;
+}
 function isRuntimePrimitiveId(value) {
     return value === 'runtime.status'
         || value === 'runtime.reasoning.set'
@@ -1512,6 +1531,193 @@ export class CanonAgent {
                     if (abortController.signal.aborted || isAbortLikeError(error)) {
                         throw error;
                     }
+                    if (!requestCreated) {
+                        throw error;
+                    }
+                    shouldPersistTurnState = false;
+                    return result;
+                }
+            };
+            const sendCard = async (request) => {
+                throwIfAborted();
+                const cardId = safeRuntimeCardId(request.cardId ?? request.card.cardId);
+                const explicitExpiresAt = request.expiresAt instanceof Date
+                    ? request.expiresAt.getTime()
+                    : typeof request.expiresAt === 'number'
+                        ? request.expiresAt
+                        : typeof request.expiresAt === 'string'
+                            ? Date.parse(request.expiresAt)
+                            : null;
+                const timeoutMs = Math.max(1_000, request.timeoutMs ?? DEFAULT_RUNTIME_INPUT_TIMEOUT_MS);
+                const expiresAtMs = explicitExpiresAt && Number.isFinite(explicitExpiresAt)
+                    ? explicitExpiresAt
+                    : Date.now() + timeoutMs;
+                // Fire-and-forget: post the durable card and return. The backend treats an
+                // action-less card as display (no pending state, no response expected).
+                await this.apiClient.createRuntimeCardRequest(buildRuntimeCardCreateArgs({ request, conversationId, cardId, fallbackTurnId: turnId, expiresAtMs }));
+                try {
+                    await turnOutput.addBlock({
+                        id: `card:${cardId}`,
+                        kind: 'status',
+                        status: 'completed',
+                        title: request.card.title,
+                        summary: request.card.template ?? 'runtime card',
+                    });
+                }
+                catch { }
+                return { status: 'displayed', cardId };
+            };
+            const requestCard = async (request) => {
+                throwIfAborted();
+                // Action-less cards are fire-and-forget display/report cards — never block.
+                const hasActions = Array.isArray(request.card.blocks)
+                    && request.card.blocks.some((block) => block.kind === 'actions');
+                if (!hasActions)
+                    return sendCard(request);
+                const cardId = safeRuntimeCardId(request.cardId ?? request.card.cardId);
+                const explicitExpiresAt = request.expiresAt instanceof Date
+                    ? request.expiresAt.getTime()
+                    : typeof request.expiresAt === 'number'
+                        ? request.expiresAt
+                        : typeof request.expiresAt === 'string'
+                            ? Date.parse(request.expiresAt)
+                            : null;
+                const timeoutMs = Math.max(1_000, request.timeoutMs ?? DEFAULT_RUNTIME_INPUT_TIMEOUT_MS);
+                const expiresAtMs = explicitExpiresAt && Number.isFinite(explicitExpiresAt)
+                    ? explicitExpiresAt
+                    : Date.now() + timeoutMs;
+                let result = { status: 'timeout', cardId };
+                let requestCreated = false;
+                let requestResolved = false;
+                const cancelPendingRequest = async () => {
+                    if (!requestCreated || requestResolved)
+                        return;
+                    try {
+                        await this.apiClient.consumeRuntimeCardResponse({
+                            conversationId,
+                            cardId,
+                            cancel: true,
+                        });
+                        requestResolved = true;
+                    }
+                    catch { }
+                };
+                shouldPersistTurnState = true;
+                try {
+                    await this.apiClient.createRuntimeCardRequest(buildRuntimeCardCreateArgs({ request, conversationId, cardId, fallbackTurnId: turnId, expiresAtMs }));
+                    requestCreated = true;
+                    try {
+                        await turnOutput.addBlock({
+                            id: `card:${cardId}`,
+                            kind: 'input',
+                            status: 'pending',
+                            title: request.card.title,
+                            summary: request.card.template ?? 'runtime card',
+                        });
+                        await turnOutput.waitingInput();
+                    }
+                    catch { }
+                    await writeTurn('waiting_input');
+                    try {
+                        await this.apiClient.setTyping(conversationId, false);
+                    }
+                    catch { }
+                    while (Date.now() < expiresAtMs) {
+                        throwIfAborted();
+                        try {
+                            const response = await this.apiClient.consumeRuntimeCardResponse({
+                                conversationId,
+                                cardId,
+                            });
+                            if (response.status === 'submitted') {
+                                requestResolved = true;
+                                result = {
+                                    status: 'submitted',
+                                    cardId,
+                                    ...(response.actionId ? { actionId: response.actionId } : {}),
+                                    ...(response.values ? { values: response.values } : {}),
+                                };
+                                break;
+                            }
+                            if (response.status === 'cancelled' || response.status === 'timeout') {
+                                requestResolved = true;
+                                result = { status: response.status, cardId };
+                                break;
+                            }
+                        }
+                        catch {
+                            // Keep waiting; the control path is the authoritative source and
+                            // transient consume failures should not leak response values.
+                        }
+                        await sleepWithAbort(Math.min(RUNTIME_INPUT_POLL_MS, Math.max(1, expiresAtMs - Date.now())), abortController.signal);
+                    }
+                    if (!requestResolved) {
+                        try {
+                            const response = await this.apiClient.consumeRuntimeCardResponse({
+                                conversationId,
+                                cardId,
+                            });
+                            if (response.status === 'submitted') {
+                                result = {
+                                    status: 'submitted',
+                                    cardId,
+                                    ...(response.actionId ? { actionId: response.actionId } : {}),
+                                    ...(response.values ? { values: response.values } : {}),
+                                };
+                            }
+                            else if (response.status === 'cancelled' || response.status === 'timeout') {
+                                result = { status: response.status, cardId };
+                            }
+                        }
+                        catch { }
+                        requestResolved = true;
+                    }
+                    // The interactive path never yields 'displayed' (that returns early via
+                    // sendCard); narrow for buildRuntimeCardOutcome's resolution status.
+                    const resolutionStatus = result.status === 'displayed' ? 'timeout' : result.status;
+                    const outcome = buildRuntimeCardOutcome(cardId, resolutionStatus, {
+                        reason: resolutionStatus,
+                    });
+                    await this.apiClient.sendMessage(conversationId, outcome.text, {
+                        metadata: {
+                            ...outcome.metadata,
+                            turnId: request.turnId ?? turnId,
+                            turnSemantics: 'control',
+                            replyBehavior: 'suppress_auto_reply',
+                        },
+                    });
+                    throwIfAborted();
+                    shouldPersistTurnState = false;
+                    try {
+                        await turnOutput.completeBlock(`card:${cardId}`, {
+                            summary: `Card ${result.status}`,
+                        });
+                    }
+                    catch { }
+                    try {
+                        await this.apiClient.setTyping(conversationId, true, 'thinking');
+                    }
+                    catch { }
+                    await setLiveState('thinking', 'Thinking...', 'thinking');
+                    return result;
+                }
+                catch (error) {
+                    const shouldSendInterruptedOutcome = requestCreated && !requestResolved;
+                    await cancelPendingRequest();
+                    if (abortController.signal.aborted || isAbortLikeError(error)) {
+                        if (shouldSendInterruptedOutcome) {
+                            const outcome = buildRuntimeCardOutcome(cardId, 'cancelled', { reason: 'interrupted' });
+                            await this.apiClient.sendMessage(conversationId, outcome.text, {
+                                metadata: {
+                                    ...outcome.metadata,
+                                    turnId: request.turnId ?? turnId,
+                                    turnSemantics: 'control',
+                                    replyBehavior: 'suppress_auto_reply',
+                                },
+                            }).catch(() => { });
+                        }
+                        throw error;
+                    }
                     shouldPersistTurnState = false;
                     return result;
                 }
@@ -1580,6 +1786,8 @@ export class CanonAgent {
                 provenance,
                 requestApproval,
                 requestRuntimeInput,
+                requestCard,
+                sendCard,
                 abortSignal: abortController.signal,
                 media: {
                     materialize: (message = hydratedMessages[hydratedMessages.length - 1], options) => {

package/dist/runtime-card.d.ts

@@ -0,0 +1,29 @@
+import type { RuntimeCardNativeMetadata, RuntimeCardV1 } from '@canonmsg/core';
+import type { RuntimeCardRequest } from './types';
+/** Arguments passed to `CanonClient.createRuntimeCardRequest`. */
+export interface RuntimeCardCreateArgs {
+    conversationId: string;
+    card: RuntimeCardV1;
+    cardId: string;
+    expiresAt: number;
+    responseUserId?: string;
+    runtimeId?: string;
+    turnId?: string;
+    native?: RuntimeCardNativeMetadata;
+}
+/**
+ * Build the `createRuntimeCardRequest` payload shared by `sendCard` (display)
+ * and `requestCard` (interactive).
+ *
+ * `responseUserId` is OMITTED unless the developer supplied one, so the Canon
+ * backend infers a reachable responder (the owner when they are a conversation
+ * member, otherwise the sole other member). Pre-filling the owner here would
+ * break agent-to-user DMs where the owner is not a member of the conversation.
+ */
+export declare function buildRuntimeCardCreateArgs(input: {
+    request: RuntimeCardRequest;
+    conversationId: string;
+    cardId: string;
+    fallbackTurnId?: string;
+    expiresAtMs: number;
+}): RuntimeCardCreateArgs;

package/dist/runtime-card.js

@@ -0,0 +1,22 @@
+/**
+ * Build the `createRuntimeCardRequest` payload shared by `sendCard` (display)
+ * and `requestCard` (interactive).
+ *
+ * `responseUserId` is OMITTED unless the developer supplied one, so the Canon
+ * backend infers a reachable responder (the owner when they are a conversation
+ * member, otherwise the sole other member). Pre-filling the owner here would
+ * break agent-to-user DMs where the owner is not a member of the conversation.
+ */
+export function buildRuntimeCardCreateArgs(input) {
+    const { request, conversationId, cardId, fallbackTurnId, expiresAtMs } = input;
+    return {
+        conversationId,
+        cardId,
+        card: { ...request.card, cardId },
+        expiresAt: expiresAtMs,
+        ...(request.responseUserId ? { responseUserId: request.responseUserId } : {}),
+        ...(request.runtimeId ? { runtimeId: request.runtimeId } : {}),
+        turnId: request.turnId ?? fallbackTurnId,
+        ...(request.native ? { native: request.native } : {}),
+    };
+}

package/dist/types.d.ts

@@ -1,5 +1,5 @@
-export type { AddMemberResult, AgentClientType, CanonGroupContext, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeDescriptor, CanonRuntimeFact, CanonRuntimeFactGroup, CanonRuntimePrimitiveId, CanonRuntimeProvenance, CanonMessage, CanonConversation, CanonReplyContext, CanonContact, CanonContactRequest, CanonResolveAdmissionResult, ContactAddedPayload, ContactRemovedPayload, ContactSource, AgentContext, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonSelfContext, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, SessionConfig, CreateConversationOptions, TurnLifecycleState, TurnOutputBlock, TurnOutputBlockInput, ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalRisk, ApprovalReplyMetadata, ApprovalOutcomeMetadata, RuntimeInputChoice, RuntimeInputAnswers, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, SessionRule, ApprovalResult, } from '@canonmsg/core';
-import type { AddMemberResult, CanonGroupContext, CanonMessage, CanonConversation, CanonReplyContext, ContactCardPayload, CanonRuntimeActionDispatch, CanonRuntimePrimitiveId, CanonRuntimeProvenance, ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalResult, ApprovalRisk, RuntimeInputChoice, RuntimeInputAnswers, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, SendMessageOptions, SendContextualSelfContextInput, SessionConfig, TurnOutputBlock, TurnOutputBlockInput } from '@canonmsg/core';
+export type { AddMemberResult, AgentClientType, CanonGroupContext, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeDescriptor, CanonRuntimeFact, CanonRuntimeFactGroup, CanonRuntimePrimitiveId, CanonRuntimeProvenance, CanonMessage, CanonConversation, CanonReplyContext, CanonContact, CanonContactRequest, CanonResolveAdmissionResult, ContactAddedPayload, ContactRemovedPayload, ContactSource, AgentContext, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonSelfContext, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, SessionConfig, CreateConversationOptions, TurnLifecycleState, TurnOutputBlock, TurnOutputBlockInput, ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalRisk, ApprovalReplyMetadata, ApprovalOutcomeMetadata, RuntimeInputChoice, RuntimeInputAnswers, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, RuntimeCardNativeMetadata, RuntimeCardV1, SessionRule, ApprovalResult, } from '@canonmsg/core';
+import type { AddMemberResult, CanonGroupContext, CanonMessage, CanonConversation, CanonReplyContext, ContactCardPayload, CanonRuntimeActionDispatch, CanonRuntimePrimitiveId, CanonRuntimeProvenance, ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalResult, ApprovalRisk, RuntimeInputChoice, RuntimeInputAnswers, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, RuntimeCardNativeMetadata, RuntimeCardV1, SendMessageOptions, SendContextualSelfContextInput, SessionConfig, TurnOutputBlock, TurnOutputBlockInput } from '@canonmsg/core';
 import type { MaterializeMediaOptions, MaterializedCanonAttachment, ReplyWithFileOptions, UploadMediaFileOptions } from './media.js';
 export interface ProgressMessageOptions extends SendMessageOptions {
     /**
@@ -85,6 +85,22 @@ export interface RuntimeInputResult {
     answers?: RuntimeInputAnswers;
     inputId: string;
 }
+export interface RuntimeCardRequest {
+    card: RuntimeCardV1;
+    cardId?: string;
+    expiresAt?: string | number | Date;
+    responseUserId?: string;
+    timeoutMs?: number;
+    runtimeId?: string;
+    turnId?: string;
+    native?: RuntimeCardNativeMetadata;
+}
+export interface RuntimeCardResult {
+    status: 'submitted' | 'cancelled' | 'timeout' | 'displayed';
+    cardId: string;
+    actionId?: string;
+    values?: Record<string, unknown>;
+}
 export interface MessageHandlerContext {
     messages: CanonMessage[];
     history: CanonMessage[];
@@ -144,6 +160,19 @@ export interface MessageHandlerContext {
      * never persisted in Canon message metadata.
      */
     requestRuntimeInput: (request: RuntimeInputRequest) => Promise<RuntimeInputResult>;
+    /**
+     * Ask the agent owner to review/respond to a generic rich card. The visible
+     * card document is redacted for presentation; raw response values return
+     * only to the calling runtime through Canon's control path.
+     */
+    requestCard: (request: RuntimeCardRequest) => Promise<RuntimeCardResult>;
+    /**
+     * Post a fire-and-forget display/report card and return immediately with
+     * `{ status: 'displayed' }` — no waiting-input lifecycle. Use requestCard for
+     * cards that expect a response. (requestCard also auto-detects action-less
+     * cards and delegates here.)
+     */
+    sendCard: (request: RuntimeCardRequest) => Promise<RuntimeCardResult>;
     /** Canon-managed local media access for the current conversation. */
     media: {
         materialize: (message?: CanonMessage, options?: Omit<MaterializeMediaOptions, 'agentId' | 'conversationId' | 'messageId'>) => Promise<MaterializedCanonAttachment[]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-sdk",
-  "version": "2.0.0",
+  "version": "2.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": "^1.0.0"
+    "@canonmsg/core": "^1.2.0"
   },
   "publishConfig": {
     "access": "public"