feat: file attachment support for Feishu (documents + audio)

- Add FileAttachment interface to ChannelMessage (mimeType, data, fileName)
- Feishu adapter: handle file and audio message types via downloadFile()
- Gateway: allow file-only messages, pass files to assistant.chat()
- Assistant: save files to .golem/files/, append file paths to prompt
- HTTP /chat endpoint: accept base64-encoded files array

Author: 0xranx

src/channel.ts

@@ -8,6 +8,16 @@ export interface ImageAttachment {
   fileName?: string;
 }
 
+/** A file (non-image) attached to an incoming IM message. */
+export interface FileAttachment {
+  /** MIME type, e.g. "application/pdf", "audio/ogg". */
+  mimeType: string;
+  /** Raw file bytes. */
+  data: Buffer;
+  /** Original filename. */
+  fileName: string;
+}
+
 export interface ChannelMessage {
   channelType: string;
   senderId: string;
@@ -19,6 +29,8 @@ export interface ChannelMessage {
   messageId?: string;
   /** Images attached to the message (downloaded by the adapter). */
   images?: ImageAttachment[];
+  /** Files (non-image) attached to the message (downloaded by the adapter). */
+  files?: FileAttachment[];
   raw: unknown;
   /**
    * Indicates whether the sender is a human user or a bot/app.

src/channels/feishu.ts

@@ -1,4 +1,11 @@
-import type { ChannelAdapter, ChannelMessage, ImageAttachment, ReadReceipt, ReplyOptions } from '../channel.js';
+import type {
+  ChannelAdapter,
+  ChannelMessage,
+  FileAttachment,
+  ImageAttachment,
+  ReadReceipt,
+  ReplyOptions,
+} from '../channel.js';
 import { importPeer } from '../peer-require.js';
 import type { FeishuChannelConfig } from '../workspace.js';
 import { hasMarkdown, markdownToCard } from './feishu-format.js';
@@ -73,6 +80,25 @@ export class FeishuAdapter implements ChannelAdapter {
     return { mimeType, data, fileName: `${imageKey}.${mimeType === 'image/png' ? 'png' : 'jpg'}` };
   }
 
+  /**
+   * Download a file resource (document, audio, etc.) from a Feishu message.
+   * Uses the same IM v1 message resource API with type=file.
+   */
+  private async downloadFile(messageId: string, fileKey: string, fileName: string): Promise<FileAttachment> {
+    const token = await this.client.tokenManager.getTenantAccessToken();
+    const resp = await fetch(
+      `https://open.feishu.cn/open-apis/im/v1/messages/${messageId}/resources/${fileKey}?type=file`,
+      { headers: { Authorization: `Bearer ${token}` } },
+    );
+    if (!resp.ok) {
+      throw new Error(`Feishu file download failed: ${resp.status} ${resp.statusText}`);
+    }
+    const data = Buffer.from(await resp.arrayBuffer());
+    const contentType = resp.headers.get('content-type') || 'application/octet-stream';
+    const mimeType = contentType.split(';')[0];
+    return { mimeType, data, fileName };
+  }
+
   async start(onMessage: (msg: ChannelMessage) => void): Promise<void> {
     let lark: any;
     try {
@@ -168,7 +194,8 @@ export class FeishuAdapter implements ChannelAdapter {
 
       // Parse message content based on type
       const msgType = message.message_type;
-      if (msgType !== 'text' && msgType !== 'image' && msgType !== 'post') return;
+      if (msgType !== 'text' && msgType !== 'image' && msgType !== 'post' && msgType !== 'file' && msgType !== 'audio')
+        return;
 
       let parsedContent: Record<string, any>;
       try {
@@ -239,6 +266,36 @@ export class FeishuAdapter implements ChannelAdapter {
         if (!text && images.length > 0) text = '(image)';
       }
 
+      // File attachment handling
+      const files: FileAttachment[] = [];
+
+      if (msgType === 'file') {
+        const fileKey = parsedContent.file_key;
+        const fileName = parsedContent.file_name || 'attachment';
+        if (fileKey) {
+          try {
+            const file = await this.downloadFile(message.message_id, fileKey, fileName);
+            files.push(file);
+            text = `(file: ${fileName})`;
+          } catch (e) {
+            console.error('[feishu] Failed to download file:', (e as Error).message);
+            return;
+          }
+        }
+      } else if (msgType === 'audio') {
+        const fileKey = parsedContent.file_key;
+        if (fileKey) {
+          try {
+            const file = await this.downloadFile(message.message_id, fileKey, 'voice.opus');
+            files.push(file);
+            text = '(audio)';
+          } catch (e) {
+            console.error('[feishu] Failed to download audio:', (e as Error).message);
+            return;
+          }
+        }
+      }
+
       // Process @mentions in text:
       // - Strip the bot's own @mention key entirely
       // - Replace other users' @mention keys with readable @Name format
@@ -253,7 +310,7 @@ export class FeishuAdapter implements ChannelAdapter {
         }
       }
 
-      if (!text && images.length === 0) return;
+      if (!text && images.length === 0 && files.length === 0) return;
 
       const senderId = sender.sender_id?.open_id || sender.sender_id?.user_id || '';
       const senderName = await this.resolveUserName(senderId);
@@ -276,6 +333,7 @@ export class FeishuAdapter implements ChannelAdapter {
         text,
         messageId: msgId,
         images: images.length > 0 ? images : undefined,
+        files: files.length > 0 ? files : undefined,
         senderType,
         mentioned: chatType === 'group' ? isMentioned : undefined,
         mentionedOthers: otherMentionNames.length > 0 ? otherMentionNames : undefined,

src/gateway.ts

@@ -319,7 +319,7 @@ export async function handleMessage(
   peers?: PeerBot[],
 ): Promise<void> {
   const userText = msg.chatType === 'group' ? stripMention(msg.text) : msg.text;
-  if (!userText && (!msg.images || msg.images.length === 0)) return;
+  if (!userText && (!msg.images || msg.images.length === 0) && (!msg.files || msg.files.length === 0)) return;
 
   // ── Slash command interception ──
   const parsed = parseCommand(userText);
@@ -493,7 +493,7 @@ export async function handleMessage(
         buffer = '';
       };
 
-      for await (const event of assistant.chat(fullText, { sessionKey, images: msg.images })) {
+      for await (const event of assistant.chat(fullText, { sessionKey, images: msg.images, files: msg.files })) {
         if (event.type === 'text') {
           fullReply += event.content;
           buffer += event.content;
@@ -558,7 +558,7 @@ export async function handleMessage(
       }
     } else {
       // ── Buffered mode (default): accumulate all text, send at end ──
-      for await (const event of assistant.chat(fullText, { sessionKey, images: msg.images })) {
+      for await (const event of assistant.chat(fullText, { sessionKey, images: msg.images, files: msg.files })) {
         if (event.type === 'text') {
           fullReply += event.content;
         } else if (event.type === 'warning') {

src/index.ts

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs';
 import { mkdir, rm, writeFile } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
-import type { ImageAttachment } from './channel.js';
+import type { FileAttachment, ImageAttachment } from './channel.js';
 import { type AgentEngine, createEngine, type DiscoveredEngine, discoverEngines, type StreamEvent } from './engine.js';
 import {
   appendHistory,
@@ -147,6 +147,8 @@ export interface ChatOpts {
   sessionKey?: string;
   /** Images attached to the user message. Saved to disk and referenced in the prompt. */
   images?: ImageAttachment[];
+  /** Files (non-image) attached to the user message. Saved to disk and referenced in the prompt. */
+  files?: FileAttachment[];
 }
 
 export interface Assistant {
@@ -221,6 +223,7 @@ export function createAssistant(opts: CreateAssistantOpts): Assistant {
     sessionKey: string,
     isRetry: boolean,
     images?: ImageAttachment[],
+    files?: FileAttachment[],
   ): AsyncIterable<StreamEvent> {
     const { config, skills } = await ensureReady(dir);
 
@@ -278,12 +281,30 @@ export function createAssistant(opts: CreateAssistantOpts): Assistant {
       }
     }
 
+    // Save attached files to workspace temp dir so the agent can read them
+    const filePaths: string[] = [];
+    const fileDir = join(dir, '.golem', 'files');
+    if (files && files.length > 0) {
+      await mkdir(fileDir, { recursive: true });
+      for (const file of files) {
+        const filePath = join(fileDir, file.fileName);
+        await writeFile(filePath, file.data);
+        filePaths.push(filePath);
+      }
+    }
+
     // Append image file paths to the message so the agent can read/view them
     if (imagePaths.length > 0) {
       const imageRefs = imagePaths.map((p) => p).join('\n');
       finalMessage += `\n\n[User attached ${imagePaths.length} image(s). File paths:\n${imageRefs}\nPlease read/view these files to see the images.]`;
     }
 
+    // Append file paths to the message so the agent can read them
+    if (filePaths.length > 0) {
+      const fileRefs = filePaths.map((p) => p).join('\n');
+      finalMessage += `\n\n[User attached ${filePaths.length} file(s). File paths:\n${fileRefs}\nPlease read these files to see the content.]`;
+    }
+
     // Prune once per process
     if (!pruneDone) {
       pruneDone = true;
@@ -339,8 +360,8 @@ export function createAssistant(opts: CreateAssistantOpts): Assistant {
       }
     } finally {
       clearTimeout(timer);
-      // Clean up temp image files
-      for (const p of imagePaths) {
+      // Clean up temp image and file attachments
+      for (const p of [...imagePaths, ...filePaths]) {
         rm(p).catch(() => {});
       }
     }
@@ -416,7 +437,7 @@ export function createAssistant(opts: CreateAssistantOpts): Assistant {
       if (isResumeFail) {
         await clearSession(dir, sessionKey);
         yield { type: 'warning' as const, message: 'Session could not be resumed. Starting fresh conversation.' };
-        yield* doChat(message, sessionKey, true, images);
+        yield* doChat(message, sessionKey, true, images, files);
       }
     }
   }
@@ -425,6 +446,7 @@ export function createAssistant(opts: CreateAssistantOpts): Assistant {
     message: string,
     sessionKey: string,
     images?: ImageAttachment[],
+    files?: FileAttachment[],
   ): AsyncIterable<StreamEvent> {
     // Rate limits use opts values directly — no file I/O before acquiring the mutex,
     // so same-key serialization order is preserved (first caller wins the lock).
@@ -455,7 +477,7 @@ export function createAssistant(opts: CreateAssistantOpts): Assistant {
     }
 
     try {
-      yield* doChat(message, sessionKey, false, images);
+      yield* doChat(message, sessionKey, false, images, files);
     } finally {
       activeChatCount--;
       mutex.release(sessionKey);
@@ -465,7 +487,7 @@ export function createAssistant(opts: CreateAssistantOpts): Assistant {
   return {
     chat(message: string, chatOpts?: ChatOpts): AsyncIterable<StreamEvent> {
       const key = chatOpts?.sessionKey || DEFAULT_SESSION_KEY;
-      return chatImpl(message, key, chatOpts?.images);
+      return chatImpl(message, key, chatOpts?.images, chatOpts?.files);
     },
 
     async init(initOpts: { engine: string; name: string; role?: string }): Promise<void> {

src/server.ts

@@ -121,6 +121,7 @@ export function createGolemServer(
         message?: string;
         sessionKey?: string;
         images?: Array<{ mimeType?: string; data?: string; fileName?: string }>;
+        files?: Array<{ mimeType?: string; data?: string; fileName?: string }>;
       };
       try {
         body = JSON.parse(await readBody(req));
@@ -129,9 +130,10 @@ export function createGolemServer(
         return;
       }
 
-      // Allow image-only messages (no text required when images are present)
+      // Allow image/file-only messages (no text required when attachments are present)
       const hasImages = Array.isArray(body.images) && body.images.length > 0;
-      if ((!body.message || typeof body.message !== 'string') && !hasImages) {
+      const hasFiles = Array.isArray(body.files) && body.files.length > 0;
+      if ((!body.message || typeof body.message !== 'string') && !hasImages && !hasFiles) {
         json(res, 400, { error: 'Missing "message" field' });
         return;
       }
@@ -153,7 +155,24 @@ export function createGolemServer(
         }
       }
 
-      const chatMessage = body.message || '(image)';
+      // Convert base64-encoded files to FileAttachment[]
+      const files: Array<{ mimeType: string; data: Buffer; fileName: string }> = [];
+      if (hasFiles) {
+        for (const f of body.files!) {
+          if (!f.data || !f.fileName) continue;
+          try {
+            files.push({
+              mimeType: f.mimeType || 'application/octet-stream',
+              data: Buffer.from(f.data, 'base64'),
+              fileName: f.fileName,
+            });
+          } catch {
+            /* skip malformed entries */
+          }
+        }
+      }
+
+      const chatMessage = body.message || (hasImages ? '(image)' : '(file)');
 
       // ── Slash command interception ──
       if (dir) {
@@ -197,6 +216,7 @@ export function createGolemServer(
         for await (const event of assistant.chat(chatMessage, {
           sessionKey: body.sessionKey,
           images: images.length > 0 ? images : undefined,
+          files: files.length > 0 ? files : undefined,
         })) {
           res.write(`data: ${JSON.stringify(event)}\n\n`);
           if (event.type === 'text') replyText += event.content;