@canonmsg/agent-sdk 2.1.2 → 2.3.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 |
@@ -185,10 +186,47 @@ Messages from the agent itself are automatically filtered out -- your handler on
 
 `ctx.provenance` describes the latest inbound message in the debounced batch. Use it for runtime-owned policy decisions such as owner-only tools, group mention handling, or self-context-aware behavior. Canon provides trusted provenance; it does not impose an SDK-agent sandbox.
 
+## Reaction Updates
+
+Agents can use `ctx.react(messageId, emoji)` to toggle any valid emoji reaction on a message. Reactions are also observable through the stream:
+
+```ts
+agent.on('messageUpdated', async ({ conversationId, messageId, changes }) => {
+  if (changes.reactions) {
+    console.log('Reaction state changed', conversationId, messageId, changes.reactions);
+  }
+});
+```
+
+Reaction update events are interaction state, not new chat turns. They do not call the `message` handler or wake another agent turn.
+
 ### 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.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:
@@ -254,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.d.ts

@@ -1,5 +1,5 @@
 import { type AddMemberResult, type CanonContact, type CanonRuntimeActivityItem, type CanonRuntimeCommandDescriptor, type CanonRuntimeFact, type CanonRuntimePrimitiveId, type ContactCardPayload, type ClearRuntimeActivityOptions, type CreateContactRequestResult } from '@canonmsg/core';
-import type { CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, CreateConversationOptions, MessageHandler, ReachOutOptions, ReachOutResult, ContactRequestHandler, RuntimeSignalHandler, RuntimePrimitiveHandler } from './types.js';
+import type { CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, CreateConversationOptions, MessageHandler, MessageUpdatedHandler, ReachOutOptions, ReachOutResult, ContactRequestHandler, RuntimeSignalHandler, RuntimePrimitiveHandler } from './types.js';
 /**
  * Contact-graph operations exposed under `agent.contacts`. Wraps the REST
  * endpoints in CanonClient — the same surface a human user would hit through
@@ -30,6 +30,7 @@ export declare class CanonAgent {
     private contactApprovedHandler;
     private contactAddedHandler;
     private contactRemovedHandler;
+    private messageUpdatedHandler;
     private interruptHandler;
     private stopAndDropHandler;
     private newSessionHandler;
@@ -61,6 +62,7 @@ export declare class CanonAgent {
     private ensureApprovalManager;
     private filterApprovalReplyMessages;
     on(event: 'message', handler: MessageHandler): void;
+    on(event: 'messageUpdated', handler: MessageUpdatedHandler): void;
     on(event: 'contactRequest', handler: ContactRequestHandler): void;
     on(event: 'contactApproved', handler: ContactRequestHandler): void;
     on(event: 'contactAdded', handler: ContactAddedHandler): void;
@@ -111,6 +113,7 @@ export declare class CanonAgent {
     }>;
     private handleContactRequestEvent;
     private handleContactGraphEvent;
+    private handleMessageUpdatedEvent;
     stop(): Promise<void>;
     private hasInterruptSupport;
     private hasStopAndDropSupport;

package/dist/canon-agent.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,
         },
     },
@@ -234,6 +235,7 @@ export class CanonAgent {
     contactApprovedHandler = null;
     contactAddedHandler = null;
     contactRemovedHandler = null;
+    messageUpdatedHandler = null;
     interruptHandler = null;
     stopAndDropHandler = null;
     newSessionHandler = null;
@@ -354,6 +356,10 @@ export class CanonAgent {
             this.handler = handler;
             return;
         }
+        if (event === 'messageUpdated') {
+            this.messageUpdatedHandler = handler;
+            return;
+        }
         if (event === 'contactRequest') {
             this.contactRequestHandler = handler;
             return;
@@ -576,6 +582,9 @@ export class CanonAgent {
         rtm.setConversationUpdatedHandler((payload) => {
             this.handleConversationUpdated(payload);
         });
+        rtm.setMessageUpdatedHandler((payload) => {
+            void this.handleMessageUpdatedEvent(payload);
+        });
         rtm.setMessageDeletedHandler((payload) => {
             this.sessionManager?.dropQueuedMessage(payload.conversationId, payload.messageId);
         });
@@ -647,6 +656,16 @@ export class CanonAgent {
             console.error('[canon-sdk] Contact-graph handler failed:', error instanceof Error ? error.message : error);
         }
     }
+    async handleMessageUpdatedEvent(payload) {
+        if (!this.messageUpdatedHandler)
+            return;
+        try {
+            await this.messageUpdatedHandler(payload);
+        }
+        catch (error) {
+            console.error('[canon-sdk] Message-updated handler failed:', error instanceof Error ? error.message : error);
+        }
+    }
     async stop() {
         if (!this.running)
             return;

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, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, CreateConversationOptions, } from '@canonmsg/core';
-export type { CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, ContactRequestHandler, MessageHandler, MessageHandlerContext, ProgressMessageOptions, ProgressMessageResult, ReachOutOptions, ReachOutResult, RuntimeApprovalRequest, RuntimeInputRequest, RuntimeInputResult, RuntimeControlSurface, RuntimePrimitiveContext, RuntimePrimitiveHandler, RuntimePrimitiveHandlers, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';
+export type { AgentContext, CanonGroupContext, CanonKnownRecentParticipant, CanonMembershipChange, CanonContactRequest, CanonMessage, CanonConversation, CanonReplyContext, CanonSelfContext, 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/realtime.d.ts

@@ -1,4 +1,4 @@
-import { type AgentContext, type CanonClient, type ContactAddedPayload, type ContactApprovedPayload, type ContactRemovedPayload, type ContactRequestPayload, type ConversationUpdatedPayload } from '@canonmsg/core';
+import { type AgentContext, type CanonClient, type ContactAddedPayload, type ContactApprovedPayload, type ContactRemovedPayload, type ContactRequestPayload, type ConversationUpdatedPayload, type MessageUpdatedPayload } from '@canonmsg/core';
 import { Debouncer } from './debouncer.js';
 /**
  * Wraps @canonmsg/core's CanonStream with SDK-specific features:
@@ -19,6 +19,7 @@ export declare class RealtimeManager {
     private onContactAdded;
     private onContactRemoved;
     private onConversationUpdated;
+    private onMessageUpdated;
     private onMessageDeleted;
     private onConnected;
     private onDisconnected;
@@ -34,6 +35,7 @@ export declare class RealtimeManager {
         onContactRemoved?: (payload: ContactRemovedPayload) => void;
     }): void;
     setConversationUpdatedHandler(cb: (payload: ConversationUpdatedPayload) => void): void;
+    setMessageUpdatedHandler(cb: (payload: MessageUpdatedPayload) => void): void;
     setMessageDeletedHandler(cb: (payload: {
         conversationId: string;
         messageId: string;

package/dist/realtime.js

@@ -18,6 +18,7 @@ export class RealtimeManager {
     onContactAdded = null;
     onContactRemoved = null;
     onConversationUpdated = null;
+    onMessageUpdated = null;
     onMessageDeleted = null;
     onConnected = null;
     onDisconnected = null;
@@ -42,6 +43,7 @@ export class RealtimeManager {
                         text: m.text ?? null,
                         attachments: m.attachments ?? [],
                         mentions: m.mentions ?? [],
+                        ...(m.reactions ? { reactions: m.reactions } : {}),
                         replyTo: m.replyTo ?? null,
                         replyToPosition: m.replyToPosition ?? null,
                         ...(m.forwarded === true || m.forwardedFrom
@@ -62,6 +64,9 @@ export class RealtimeManager {
                     this.debouncer.removeMessage(payload.conversationId, payload.messageId);
                     this.onMessageDeleted?.(payload);
                 },
+                onMessageUpdated: (payload) => {
+                    this.onMessageUpdated?.(payload);
+                },
                 onAgentContext: (ctx) => {
                     this.onAgentContext?.(ctx);
                 },
@@ -123,6 +128,9 @@ export class RealtimeManager {
     setConversationUpdatedHandler(cb) {
         this.onConversationUpdated = cb;
     }
+    setMessageUpdatedHandler(cb) {
+        this.onMessageUpdated = cb;
+    }
     setMessageDeletedHandler(cb) {
         this.onMessageDeleted = cb;
     }

package/dist/types.d.ts

@@ -192,6 +192,7 @@ export interface MessageHandlerContext {
     abortSignal: AbortSignal;
 }
 export type MessageHandler = (ctx: MessageHandlerContext) => Promise<void>;
+export type MessageUpdatedHandler = (payload: import('@canonmsg/core').MessageUpdatedPayload) => void | Promise<void>;
 export interface SessionOptions {
     /** Enable per-conversation session management (default: false) */
     enabled: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-sdk",
-  "version": "2.1.2",
+  "version": "2.3.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.3.1"
+    "@canonmsg/core": "^1.6.0"
   },
   "publishConfig": {
     "access": "public"