@canonmsg/agent-sdk 0.7.1 → 0.8.1

package/README.md

@@ -117,7 +117,7 @@ This is the easiest way to build agents that need per-conversation memory or que
 
 ## Media
 
-Normalized Canon messages always expose `attachments[]` as the canonical media contract. The SDK also keeps `imageUrl` and `audioUrl` on messages for legacy compatibility, but new integrations should prefer `attachments`.
+Normalized Canon messages always expose `attachments[]` as the single canonical media contract. Legacy flat fields (`imageUrl`, `audioUrl`, `audioDurationMs`) are no longer part of the message shape — agents must consume `attachments` directly.
 
 Use the handler `media` helpers when you need the actual file bytes:
 

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 export { CanonAgent } from './canon-agent.js';
 export { CanonApiError } from '@canonmsg/core';
 export { SessionManager } from './session-manager.js';
-export { getMessageAttachments, inferUploadMimeType, materializeAttachment, materializeMessageMedia, uploadMediaFile, } from './media.js';
-export type { MaterializeMediaOptions, MaterializedCanonAttachment, ReplyWithFileOptions, UploadMediaFileOptions, } from './media.js';
+export { getCodexImagePath, getMessageAttachments, inferUploadMimeType, isAnthropicImageAttachment, materializeAttachment, materializeMessageMedia, resolveAttachmentMimeType, toAnthropicImageBlock, uploadMediaFile, } from './media.js';
+export type { AnthropicImageBlock, AnthropicImageMimeType, MaterializeMediaOptions, MaterializedCanonAttachment, ReplyWithFileOptions, UploadMediaFileOptions, } from './media.js';
 export type { SessionConfig, Session } from './session-manager.js';
 export type { AgentContext, CanonMessage, CanonConversation, CanonResolvedWorkSession, CanonWorkSession, CanonWorkSessionContext, CanonWorkSessionConversationRole, CanonWorkSessionDisclosureMode, CanonWorkSessionParticipant, CanonWorkSessionStatus, CreateWorkSessionOptions, SendLinkedMessageOptions, SendLinkedMessageResult, SendMessageOptions, CreateConversationOptions, UpdateWorkSessionConversationOptions, } from '@canonmsg/core';
 export type { SDKMessage, SDKConversation, CanonAgentOptions, MessageHandler, MessageHandlerContext, ProgressMessageOptions, ProgressMessageResult, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';

package/dist/index.js

@@ -1,4 +1,4 @@
 export { CanonAgent } from './canon-agent.js';
 export { CanonApiError } from '@canonmsg/core';
 export { SessionManager } from './session-manager.js';
-export { getMessageAttachments, inferUploadMimeType, materializeAttachment, materializeMessageMedia, uploadMediaFile, } from './media.js';
+export { getCodexImagePath, getMessageAttachments, inferUploadMimeType, isAnthropicImageAttachment, materializeAttachment, materializeMessageMedia, resolveAttachmentMimeType, toAnthropicImageBlock, uploadMediaFile, } from './media.js';

package/dist/media.d.ts

@@ -20,13 +20,55 @@ export interface MaterializedCanonAttachment extends MediaAttachment {
     conversationId: string;
     messageId: string;
 }
-export declare function getMessageAttachments(message: Pick<CanonMessage, 'attachments' | 'imageUrl' | 'audioUrl' | 'audioDurationMs'>): MediaAttachment[];
+/**
+ * Anthropic `image` content blocks only accept these MIME types for
+ * base64 sources. Anything outside this set must either be re-encoded or
+ * degraded to a text reference.
+ */
+export type AnthropicImageMimeType = 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp';
+/**
+ * Structural shape of an Anthropic `ImageBlockParam` (base64 source). We
+ * do not import from `@anthropic-ai/sdk` here because the agent-sdk must
+ * stay dependency-free; the Claude Code plugin re-casts to the SDK type.
+ */
+export interface AnthropicImageBlock {
+    type: 'image';
+    source: {
+        type: 'base64';
+        media_type: AnthropicImageMimeType;
+        data: string;
+    };
+}
+export declare function getMessageAttachments(message: Pick<CanonMessage, 'attachments'>): MediaAttachment[];
 export declare function materializeAttachment(attachment: MediaAttachment, options: MaterializeMediaOptions & {
     index?: number;
 }): Promise<MaterializedCanonAttachment>;
-export declare function materializeMessageMedia(message: Pick<CanonMessage, 'id' | 'attachments' | 'imageUrl' | 'audioUrl' | 'audioDurationMs'>, options: Omit<MaterializeMediaOptions, 'messageId'>): Promise<MaterializedCanonAttachment[]>;
+export declare function materializeMessageMedia(message: Pick<CanonMessage, 'id' | 'attachments'>, options: Omit<MaterializeMediaOptions, 'messageId'>): Promise<MaterializedCanonAttachment[]>;
 export declare function inferUploadMimeType(filePath: string, overrideMimeType?: string): string;
 export declare function uploadMediaFile(client: CanonClient, conversationId: string, filePath: string, options?: UploadMediaFileOptions): Promise<{
     url: string;
     attachment: MediaAttachment;
 }>;
+/**
+ * Resolve the effective MIME type of a materialized attachment, falling back
+ * to filename/URL extensions when the server didn't tell us explicitly.
+ */
+export declare function resolveAttachmentMimeType(attachment: MaterializedCanonAttachment): string | null;
+/**
+ * True when a materialized attachment can be sent to Anthropic as a base64
+ * `image` block (jpeg, png, gif, webp). Other images (heic, tiff, svg, …)
+ * must be re-encoded before they can be delivered as a vision block.
+ */
+export declare function isAnthropicImageAttachment(attachment: MaterializedCanonAttachment): boolean;
+/**
+ * Read the materialized bytes and build an Anthropic `image` content block.
+ * Callers should first check `isAnthropicImageAttachment`; this function
+ * throws if the MIME type is not supported.
+ */
+export declare function toAnthropicImageBlock(attachment: MaterializedCanonAttachment): Promise<AnthropicImageBlock>;
+/**
+ * Return the local path to pass to Codex via its `-i/--image` flag when the
+ * attachment is an image Codex can consume. Codex accepts the same MIME types
+ * as Anthropic in practice (jpeg/png/gif/webp), so we reuse the allowlist.
+ */
+export declare function getCodexImagePath(attachment: MaterializedCanonAttachment): string | null;

package/dist/media.js

@@ -1,6 +1,12 @@
 import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
 import { basename, dirname, extname, join } from 'node:path';
 import { CANON_DIR, } from '@canonmsg/core';
+const ANTHROPIC_IMAGE_MIME_TYPES = new Set([
+    'image/jpeg',
+    'image/png',
+    'image/gif',
+    'image/webp',
+]);
 const DEFAULT_MEDIA_CACHE_DIR = join(CANON_DIR, 'media-cache');
 const EXTENSION_BY_MIME = {
     'application/json': 'json',
@@ -88,25 +94,7 @@ async function fileExists(path) {
     }
 }
 export function getMessageAttachments(message) {
-    if (Array.isArray(message.attachments) && message.attachments.length > 0) {
-        return message.attachments;
-    }
-    if (message.audioUrl) {
-        return [{
-                kind: 'audio',
-                url: message.audioUrl,
-                ...(typeof message.audioDurationMs === 'number'
-                    ? { durationMs: message.audioDurationMs }
-                    : {}),
-            }];
-    }
-    if (message.imageUrl) {
-        return [{
-                kind: 'image',
-                url: message.imageUrl,
-            }];
-    }
-    return [];
+    return Array.isArray(message.attachments) ? message.attachments : [];
 }
 export async function materializeAttachment(attachment, options) {
     const path = buildCachePath({
@@ -164,3 +152,63 @@ export async function uploadMediaFile(client, conversationId, filePath, options)
     const fileName = options?.fileName ?? basename(filePath);
     return client.uploadMedia(conversationId, buffer.toString('base64'), mimeType, fileName);
 }
+/**
+ * Resolve the effective MIME type of a materialized attachment, falling back
+ * to filename/URL extensions when the server didn't tell us explicitly.
+ */
+export function resolveAttachmentMimeType(attachment) {
+    if (attachment.mimeType)
+        return attachment.mimeType.toLowerCase();
+    const pathExt = extname(attachment.path).toLowerCase();
+    const fromPath = MIME_BY_EXTENSION[pathExt];
+    if (fromPath)
+        return fromPath;
+    const fileExt = extname(attachment.fileName ?? '').toLowerCase();
+    const fromFileName = MIME_BY_EXTENSION[fileExt];
+    if (fromFileName)
+        return fromFileName;
+    const urlExt = extname(attachment.sourceUrl.split('?')[0] ?? '').toLowerCase();
+    const fromUrl = MIME_BY_EXTENSION[urlExt];
+    if (fromUrl)
+        return fromUrl;
+    return null;
+}
+/**
+ * True when a materialized attachment can be sent to Anthropic as a base64
+ * `image` block (jpeg, png, gif, webp). Other images (heic, tiff, svg, …)
+ * must be re-encoded before they can be delivered as a vision block.
+ */
+export function isAnthropicImageAttachment(attachment) {
+    if (attachment.kind !== 'image')
+        return false;
+    const mime = resolveAttachmentMimeType(attachment);
+    return mime != null && ANTHROPIC_IMAGE_MIME_TYPES.has(mime);
+}
+/**
+ * Read the materialized bytes and build an Anthropic `image` content block.
+ * Callers should first check `isAnthropicImageAttachment`; this function
+ * throws if the MIME type is not supported.
+ */
+export async function toAnthropicImageBlock(attachment) {
+    if (!isAnthropicImageAttachment(attachment)) {
+        throw new Error(`Canon attachment ${attachment.index} is not a supported Anthropic image (kind=${attachment.kind}, mime=${attachment.mimeType ?? 'unknown'})`);
+    }
+    const mediaType = resolveAttachmentMimeType(attachment);
+    const buffer = await readFile(attachment.path);
+    return {
+        type: 'image',
+        source: {
+            type: 'base64',
+            media_type: mediaType,
+            data: buffer.toString('base64'),
+        },
+    };
+}
+/**
+ * Return the local path to pass to Codex via its `-i/--image` flag when the
+ * attachment is an image Codex can consume. Codex accepts the same MIME types
+ * as Anthropic in practice (jpeg/png/gif/webp), so we reuse the allowlist.
+ */
+export function getCodexImagePath(attachment) {
+    return isAnthropicImageAttachment(attachment) ? attachment.path : null;
+}

package/dist/realtime.js

@@ -37,13 +37,16 @@ export class RealtimeManager {
                         isOwner: m.isOwner ?? false,
                         contentType: m.contentType ?? 'text',
                         text: m.text ?? null,
-                        imageUrl: m.imageUrl ?? null,
-                        audioUrl: m.audioUrl ?? null,
-                        audioDurationMs: m.audioDurationMs ?? null,
                         attachments: m.attachments ?? [],
                         mentions: m.mentions ?? [],
                         replyTo: m.replyTo ?? null,
                         replyToPosition: m.replyToPosition ?? null,
+                        ...(m.forwarded === true || m.forwardedFrom
+                            ? { forwarded: true }
+                            : {}),
+                        ...(m.forwardedFrom
+                            ? { forwardedFrom: m.forwardedFrom }
+                            : {}),
                         status: 'sent',
                         deleted: false,
                         createdAt: m.createdAt ?? new Date().toISOString(),

package/package.json

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