feat(channels): add media attachment types and cache directory

Add ChannelMediaAttachment type with support for audio, image, video,
and document media types. Extend ChannelMessage with optional media
field and ChannelPlugin with optional downloadMedia method.
Add MEDIA_CACHE_DIR path for downloaded media files.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

src/channels/types.ts

@@ -7,6 +7,25 @@
 
 import type { BlockChunkerConfig } from "../hub/block-chunker.js";
 
+// ─── Media Attachment ───
+
+/** Media type for incoming channel attachments */
+export type ChannelMediaType = "audio" | "image" | "video" | "document";
+
+/** Media attachment from a channel message */
+export interface ChannelMediaAttachment {
+  /** Media type */
+  type: ChannelMediaType;
+  /** Platform-specific file ID (used for download) */
+  fileId: string;
+  /** MIME type if known (e.g. "audio/ogg", "image/jpeg") */
+  mimeType?: string | undefined;
+  /** Duration in seconds (for audio/video) */
+  duration?: number | undefined;
+  /** Caption text attached to the media */
+  caption?: string | undefined;
+}
+
 // ─── Normalized Incoming Message ───
 
 /** Platform-agnostic incoming message */
@@ -21,6 +40,8 @@ export interface ChannelMessage {
   text: string;
   /** Chat type: "direct" (1:1) or "group" */
   chatType: "direct" | "group";
+  /** Optional media attachment (voice, image, video, document) */
+  media?: ChannelMediaAttachment | undefined;
 }
 
 // ─── Delivery Context ───
@@ -96,6 +117,8 @@ export interface ChannelPlugin {
   readonly gateway: ChannelGatewayAdapter;
   /** Message sending adapter */
   readonly outbound: ChannelOutboundAdapter;
+  /** Download a media file to local disk (optional, platform-specific) */
+  downloadMedia?(fileId: string, accountId: string): Promise<string>;
 }
 
 // ─── Channels Config File Shape ───

src/shared/paths.ts

@@ -3,3 +3,6 @@ import { homedir } from "node:os";
 
 /** Root data directory: ~/.super-multica */
 export const DATA_DIR = join(homedir(), ".super-multica");
+
+/** Cache directory for downloaded media files */
+export const MEDIA_CACHE_DIR = join(DATA_DIR, "cache", "media");