@canonmsg/agent-sdk 2.2.0 → 2.4.0

package/README.md

@@ -176,6 +176,7 @@ The `message` event handler receives a context object with:
 | `provenance` | `CanonRuntimeProvenance` | Canon-computed sender/conversation context for the latest inbound message in this batch |
 | `requestApproval` | `(request) => Promise<ApprovalResult>` | Render a Canon approval card, wait for a response, and return the decision to the runtime |
 | `requestRuntimeInput` | `(request) => Promise<RuntimeInputResult>` | Render a Canon input card for clarification, sudo, or secret values |
+| `requestCard` / `sendCard` | functions | Render a generic `canon.card.v1` rich card; action cards can return `{ actionId, values }` |
 | `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 |
 | `turn` | `TurnController \| undefined` | Live turn-state helpers for thinking/streaming/tool/waiting-input |
@@ -203,6 +204,29 @@ Reaction update events are interaction state, not new chat turns. They do not ca
 
 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.requestCard(...)` for generic rich reports and action forms. A `canon.card.v1` action may include small structured fields; Canon validates the selected action and declared field values, but your runtime still decides what to do with them:
+
+```ts
+const review = await ctx.requestCard({
+  card: {
+    schema: 'canon.card.v1',
+    title: 'Review draft',
+    fallbackText: 'Review draft: approve or request changes.',
+    blocks: [{
+      kind: 'actions',
+      actions: [
+        { id: 'approve', label: 'Approve', tone: 'positive' },
+        {
+          id: 'revise',
+          label: 'Request changes',
+          fields: [{ id: 'note', label: 'What should change?', type: 'textarea', required: true }],
+        },
+      ],
+    }],
+  },
+});
+```
+
 ## Contact Request Awareness
 
 Agents can also observe contact-request lifecycle events without becoming the approver:
@@ -268,6 +292,8 @@ agent.on('message', async ({ messages, media }) => {
 - `media.uploadFile(path, options?)` uploads a local file into the current Canon conversation and returns the canonical attachment metadata.
 - `media.replyWithFile(path, text?, options?)` uploads a local file and sends it as the durable final Canon reply for the current turn.
 
+GIFs are regular image attachments. Agents can receive or send them through `attachments[]` with `kind: 'image'` and `mimeType: 'image/gif'`; Canon does not use a separate GIF content type.
+
 The public helpers are also available from the Node-only subpath export:
 
 ```typescript

package/dist/canon-agent.js

@@ -1,4 +1,4 @@
-import { ApprovalManager, CanonClient, buildCanonGroupContext, createTurnOutputController, createRuntimeStatePublisher, createTypingStatusPublisher, 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 { ApprovalManager, CanonClient, buildCanonTurnEnvelopeV1, buildCanonGroupContext, buildParticipationHistorySnapshot, createTurnOutputController, createRuntimeStatePublisher, createTypingStatusPublisher, diffCanonMemberIds, FINAL_MESSAGE_HANDOFF_MS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildRuntimeCardOutcome, buildRuntimeInputOutcome, initRTDBAuth, rtdbRead, rtdbWrite, normalizeTurnMetadata, reachOutToCanonContact, resolveCanonReplyContext, resolveMessageActiveSelfContextId, resolveRuntimeProvenance, selectActiveSelfContexts, renderCanonHostInboundContent, } from '@canonmsg/core';
 import { randomUUID } from 'node:crypto';
 import { AuthManager } from './auth.js';
 import { Debouncer } from './debouncer.js';
@@ -32,6 +32,7 @@ const DEFAULT_SDK_RUNTIME_DESCRIPTOR = {
             result: 'action_or_values',
             maxTimeoutMs: 30 * 60_000,
             blockKinds: ['summary', 'metricGrid', 'chart', 'table', 'list', 'callout', 'actions'],
+            actionFieldTypes: ['text', 'textarea', 'select', 'multiSelect', 'boolean'],
             native: true,
         },
     },
@@ -1332,6 +1333,37 @@ export class CanonAgent {
                 agent,
                 membershipChange,
             });
+            const participationHistory = buildParticipationHistorySnapshot(history, agent.agentId);
+            const turnEnvelope = buildCanonTurnEnvelopeV1({
+                content: latestMessage ? renderCanonHostInboundContent(latestMessage) : '[Empty message]',
+                conversationId,
+                participantContext: {
+                    conversationType: conversation.type,
+                    memberCount: conversation.memberIds.length,
+                    senderType: latestMessage?.senderType ?? provenance.sender.type,
+                    senderName: latestMessage?.senderName
+                        ?? provenance.sender.name
+                        ?? latestMessage?.senderId
+                        ?? provenance.sender.id
+                        ?? 'unknown',
+                    isOwner: provenance.sender.isOwner,
+                    mentionedAgent: provenance.mentionedAgent,
+                    ...(groupContext ? { groupContext } : {}),
+                    ...(groupContext && membershipChange ? { groupContextMode: 'membership_change' } : {}),
+                    recentSenderTypes: participationHistory.recentSenderTypes,
+                    recentHumanCount: participationHistory.recentHumanCount,
+                    recentAgentCount: participationHistory.recentAgentCount,
+                    consecutiveAgentTurns: participationHistory.consecutiveAgentTurns,
+                    currentAgentStreakStartedByHuman: participationHistory.currentAgentStreakStartedByHuman,
+                },
+                behavior: page.behavior ?? conversation.behavior,
+                selfContexts,
+                activeSelfContextId,
+                provenance,
+                replyContext,
+                message: latestMessage ?? undefined,
+                hydratedFromPage: true,
+            });
             // Build context methods bound to this conversation
             const deleteMessage = (messageId) => this.apiClient.deleteMessage(conversationId, messageId);
             const markAsRead = () => this.apiClient.markAsRead(conversationId);
@@ -1812,6 +1844,7 @@ export class CanonAgent {
                 activeSelfContextId,
                 selfContexts,
                 provenance,
+                turnEnvelope,
                 requestApproval,
                 requestRuntimeInput,
                 requestCard,

package/dist/index.d.ts

@@ -6,5 +6,5 @@ export { SessionManager } from './session-manager.js';
 export { DEFAULT_MEDIA_CACHE_DIR, getCodexImagePath, getMessageAttachments, inferUploadMimeType, isAnthropicImageAttachment, materializeAttachment, materializeMessageMedia, materializeReplyContextMedia, resolveAttachmentMimeType, sendMediaFileMessage, toAnthropicImageBlock, uploadMediaFile, } from './media.js';
 export type { AnthropicImageBlock, AnthropicImageMimeType, MaterializeMediaOptions, MaterializedCanonAttachment, MaterializedCanonReplyContext, ReplyWithFileOptions, UploadMediaFileOptions, } from './media.js';
 export type { SessionConfig, Session } from './session-manager.js';
-export type { AgentContext, CanonGroupContext, CanonKnownRecentParticipant, CanonMembershipChange, CanonContactRequest, CanonMessage, CanonConversation, CanonReplyContext, CanonSelfContext, MessageUpdatedPayload, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, CreateConversationOptions, } from '@canonmsg/core';
+export type { AgentContext, CanonGroupContext, CanonKnownRecentParticipant, CanonMembershipChange, CanonContactRequest, CanonMessage, CanonConversation, CanonReplyContext, CanonSelfContext, CanonTurnEnvelopeV1, MessageUpdatedPayload, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, CreateConversationOptions, } from '@canonmsg/core';
 export type { CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, ContactRequestHandler, MessageHandler, MessageHandlerContext, MessageUpdatedHandler, ProgressMessageOptions, ProgressMessageResult, ReachOutOptions, ReachOutResult, RuntimeApprovalRequest, RuntimeInputRequest, RuntimeInputResult, RuntimeControlSurface, RuntimePrimitiveContext, RuntimePrimitiveHandler, RuntimePrimitiveHandlers, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';

package/dist/media.js

@@ -17,6 +17,10 @@ const EXTENSION_BY_MIME = {
     'audio/ogg': 'ogg',
     'audio/webm': 'webm',
     'audio/wav': 'wav',
+    'video/mp4': 'mp4',
+    'video/quicktime': 'mov',
+    'video/webm': 'webm',
+    'video/x-m4v': 'm4v',
     'image/gif': 'gif',
     'image/jpeg': 'jpg',
     'image/png': 'png',
@@ -36,6 +40,9 @@ const MIME_BY_EXTENSION = {
     '.txt': 'text/plain',
     '.wav': 'audio/wav',
     '.webm': 'audio/webm',
+    '.m4v': 'video/x-m4v',
+    '.mov': 'video/quicktime',
+    '.mp4': 'video/mp4',
     '.webp': 'image/webp',
     '.zip': 'application/zip',
 };

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, 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';
+export type { AddMemberResult, AgentClientType, CanonGroupContext, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeDescriptor, CanonRuntimeFact, CanonRuntimeFactGroup, CanonRuntimePrimitiveId, CanonRuntimeProvenance, CanonTurnEnvelopeV1, 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, CanonTurnEnvelopeV1, 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 {
     /**
@@ -148,6 +148,8 @@ export interface MessageHandlerContext {
     selfContexts?: import('@canonmsg/core').CanonSelfContext[];
     /** Trusted Canon provenance for the latest inbound message in this handler batch. */
     provenance: CanonRuntimeProvenance;
+    /** Compact canonical turn envelope for the latest inbound message in this handler batch. */
+    turnEnvelope: CanonTurnEnvelopeV1;
     /**
      * Ask the conversation owner to approve a native runtime action. This only
      * renders Canon's inline approval card; runtimes must explicitly wait for

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-sdk",
-  "version": "2.2.0",
+  "version": "2.4.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.4.0"
+    "@canonmsg/core": "^1.7.0"
   },
   "publishConfig": {
     "access": "public"