@canonmsg/agent-sdk 2.2.0 → 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 |
@@ -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

@@ -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,
         },
     },

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/package.json

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