Support media in chat session (#358)

* ✨ (storage): add local file storage option and base64 image conversion for Claude prompts

* ♻️ (storage.ts): remove redundant useLocalStorage variable and ensure non-null assertions for S3 credentials and bucket name.

* ♻️ (chat-sessions): refactor image handling to use URL-based images instead of base64 conversion and remove local storage support

Author: nsosio

.env.local

@@ -128,6 +128,8 @@ SENTRY_ENVIRONMENT=
 
 # S3: storage configuration
 # ------------------------------------------------------------------------------------
+# S3 Storage (Digital Ocean Spaces)
+S3_ENABLED=false
 S3_REGION=fra1
 S3_ENDPOINT=https://fra1.digitaloceanspaces.com
 S3_BUCKET=your-bucket-name

.env.prod

@@ -76,6 +76,8 @@ SENTRY_ENVIRONMENT=production
 
 # S3: storage configuration
 # ------------------------------------------------------------------------------------
+# S3 Storage (Digital Ocean Spaces)
+S3_ENABLED=true
 S3_REGION=fra1
 S3_ENDPOINT=https://fra1.digitaloceanspaces.com
 S3_BUCKET=${S3_BUCKET}

.env.stage

@@ -76,6 +76,8 @@ SENTRY_ENVIRONMENT=stage
 
 # S3: storage configuration
 # ------------------------------------------------------------------------------------
+# S3 Storage (Digital Ocean Spaces)
+S3_ENABLED=true
 S3_REGION=fra1
 S3_ENDPOINT=https://fra1.digitaloceanspaces.com
 S3_BUCKET=${S3_BUCKET}

docker-compose.local.yml

@@ -54,6 +54,7 @@ services:
       - .:/app:cached
       - /app/node_modules
       - /app/.next
+      - /dev/null:/app/.env.local:ro # Shadow .env.local with empty file
       - /var/run/docker.sock:/var/run/docker.sock
     depends_on:
       postgres:
@@ -70,6 +71,7 @@ services:
       - .:/app:cached
       - /app/node_modules
       - /app/.next
+      - /dev/null:/app/.env.local:ro # Shadow .env.local with empty file
       - /var/run/docker.sock:/var/run/docker.sock
     depends_on:
       redis:

knip.config.ts

@@ -30,7 +30,6 @@ const knipConfig: KnipConfig = {
         '@radix-ui/*',
         'embla-carousel-react',
         'input-otp',
-        'react-resizable-panels',
         'vaul',
         'ts-node',
         'react-hook-form',

src/app/api/projects/[id]/chat-sessions/[sessionId]/route.ts

@@ -18,9 +18,13 @@ import { buildQueue } from '@/lib/queue';
 import { getSandboxConfig, getSandboxManager, SandboxClient } from '@/lib/sandbox';
 import { getSandboxDatabaseUrl } from '@/lib/sandbox/database';
 import { MessageAttachmentPayload, uploadFile } from '@/lib/storage';
+import type { ImageUrlContent } from '@/lib/types';
 import * as Sentry from '@sentry/nextjs';
 import { eq } from 'drizzle-orm';
 
+// Supported image media types for Claude multipart prompts
+const IMAGE_MEDIA_TYPES = ['image/jpeg', 'image/png', 'image/gif', 'image/webp'] as const;
+
 // Schema for updating a chat session
 const updateChatSessionSchema = z.object({
   title: z.string().min(1).max(100).optional(),
@@ -65,7 +69,7 @@ async function saveUploadedFile(file: File, projectId: string): Promise<MessageA
 }
 
 /**
- * Process a FormData request and extract the content and attachment
+ * Process a FormData request and extract the content and attachments
  */
 async function processFormDataRequest(
   req: NextRequest,
@@ -89,6 +93,7 @@ async function processFormDataRequest(
   for (let i = 0; i < attachmentCount; i++) {
     const attachmentFile = formData.get(`attachment_${i}`) as File | null;
     if (attachmentFile) {
+      // Upload to S3 for storage/display
       const attachment = await saveUploadedFile(attachmentFile, projectId);
       attachments.push(attachment);
     }
@@ -358,6 +363,7 @@ export async function POST(
     const contentType = req.headers.get('content-type') || '';
     let messageContent: string;
     let attachmentPayloads: MessageAttachmentPayload[] = [];
+    let imageUrls: ImageUrlContent[] = []; // URL-based images for Claude (fetched by CLI)
 
     if (contentType.includes('multipart/form-data')) {
       // Process FormData request (for file uploads)
@@ -366,12 +372,27 @@ export async function POST(
       messageContent = formData.content;
       attachmentPayloads = formData.attachments;
 
+      // Build URL-based image objects from uploaded attachments
+      // CLI will fetch these URLs and convert to base64 for Claude
+      imageUrls = attachmentPayloads
+        .filter(a =>
+          IMAGE_MEDIA_TYPES.includes(a.upload.mediaType as (typeof IMAGE_MEDIA_TYPES)[number])
+        )
+        .map(a => ({
+          mediaType: a.upload.mediaType as ImageUrlContent['mediaType'],
+          url: a.upload.fileUrl,
+        }));
+
       if (attachmentPayloads.length > 0) {
-        console.log(`⬆️ ${attachmentPayloads.length} file(s) uploaded`);
+        console.log(`📎 ${attachmentPayloads.length} file(s) attached`);
         attachmentPayloads.forEach((attachment, index) => {
-          console.log(`⬆️ Attachment [${index + 1}] uploaded: ${attachment.upload.fileUrl}`);
+          console.log(`📎 Attachment [${index + 1}]: ${attachment.upload.fileUrl}`);
         });
       }
+
+      if (imageUrls.length > 0) {
+        console.log(`🖼️ ${imageUrls.length} image URL(s) prepared for Claude`);
+      }
     } else {
       // Process JSON request for text messages
       console.log('Processing JSON request for streaming');
@@ -533,6 +554,7 @@ export async function POST(
           // Stream events from kosuke serve /api/plan (plan phase only)
           const planStream = sandboxClient.streamPlan(messageContent, '/app/project', {
             resume: claudeSessionId, // Resume previous conversation if exists
+            ...(imageUrls.length > 0 && { images: imageUrls }), // Include image URLs (fetched by CLI)
           });
 
           for await (const event of planStream) {

src/instrumentation.ts

@@ -6,6 +6,7 @@ import * as Sentry from '@sentry/nextjs';
  */
 function validateEnvironmentVariables() {
   const sentryEnabled = process.env.SENTRY_ENABLED !== 'false';
+  const s3Enabled = process.env.S3_ENABLED === 'true';
 
   const requiredEnvVars = [
     // Database
@@ -56,13 +57,6 @@ function validateEnvironmentVariables() {
     // Domain Configuration
     { key: 'TRAEFIK_ENABLED', description: 'Enable Traefik reverse proxy' },
 
-    // Digital Ocean Spaces (Storage)
-    { key: 'S3_REGION', description: 'Digital Ocean Spaces region' },
-    { key: 'S3_ENDPOINT', description: 'Digital Ocean Spaces endpoint URL' },
-    { key: 'S3_BUCKET', description: 'Digital Ocean Spaces bucket name' },
-    { key: 'S3_ACCESS_KEY_ID', description: 'Digital Ocean Spaces access key' },
-    { key: 'S3_SECRET_ACCESS_KEY', description: 'Digital Ocean Spaces secret key' },
-
     // Redis Configuration
     { key: 'REDIS_PASSWORD', description: 'Redis password' },
     { key: 'REDIS_URL', description: 'Redis connection URL for job queue' },
@@ -85,6 +79,17 @@ function validateEnvironmentVariables() {
     ...(sentryEnabled
       ? [{ key: 'SENTRY_AUTH_TOKEN', description: 'Sentry authentication token' }]
       : []),
+
+    // Digital Ocean Spaces (S3) - only required when S3_ENABLED=true
+    ...(s3Enabled
+      ? [
+          { key: 'S3_REGION', description: 'Digital Ocean Spaces region' },
+          { key: 'S3_ENDPOINT', description: 'Digital Ocean Spaces endpoint URL' },
+          { key: 'S3_BUCKET', description: 'Digital Ocean Spaces bucket name' },
+          { key: 'S3_ACCESS_KEY_ID', description: 'Digital Ocean Spaces access key' },
+          { key: 'S3_SECRET_ACCESS_KEY', description: 'Digital Ocean Spaces secret key' },
+        ]
+      : []),
   ];
 
   const missingVars = requiredEnvVars.filter(({ key }) => !process.env[key]);

src/lib/sandbox/client.ts

@@ -3,6 +3,8 @@
  * HTTP client for communicating with sandbox containers
  */
 
+import type { ImageInput } from '@/lib/types';
+
 import { getSandboxConfig } from './config';
 import { getSandboxManager } from './manager';
 import type { FileInfo, GitPullResponse, GitRevertResponse } from './types';
@@ -180,6 +182,7 @@ export class SandboxClient {
     options?: {
       noTest?: boolean;
       resume?: string | null;
+      images?: ImageInput[]; // Optional images (base64 or URL - CLI will normalize)
     }
   ): AsyncGenerator<Record<string, unknown>> {
     const config = getSandboxConfig();
@@ -198,6 +201,7 @@ export class SandboxClient {
         cwd,
         noTest,
         resume: options?.resume,
+        images: options?.images,
       }),
     });
 

src/lib/storage.ts

@@ -6,18 +6,17 @@ import { Readable } from 'node:stream';
 import type { FileType } from './db/schema';
 
 // S3 Client configuration for Digital Ocean Spaces
-// Used for both development and production environments
 const s3Client = new S3Client({
   endpoint: process.env.S3_ENDPOINT,
   region: process.env.S3_REGION,
   credentials: {
-    accessKeyId: process.env.S3_ACCESS_KEY_ID || '',
-    secretAccessKey: process.env.S3_SECRET_ACCESS_KEY || '',
+    accessKeyId: process.env.S3_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.S3_SECRET_ACCESS_KEY!,
   },
   forcePathStyle: false, // Digital Ocean Spaces uses virtual-hosted-style
 });
 
-const S3_BUCKET = process.env.S3_BUCKET || '';
+const S3_BUCKET = process.env.S3_BUCKET;
 
 export interface MessageAttachmentPayload {
   upload: UploadResult;
@@ -126,8 +125,7 @@ async function uploadFileToS3(
 }
 
 /**
- * Generic file upload function
- * Uploads files to Digital Ocean Spaces in both development and production
+ * Upload file to S3 storage
  * @param file File to upload
  * @param prefix Optional prefix for organizing files (e.g., 'documents/', 'images/')
  * @returns Upload result with file metadata

src/lib/types/chat.ts

@@ -161,6 +161,21 @@ export interface Attachment {
   createdAt: Date;
 }
 
+// Base64-encoded image content for Claude multipart prompts (internal, used in ImageInput union)
+interface ImageContent {
+  mediaType: 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp';
+  data: string; // base64-encoded image data
+}
+
+// URL-based image content (fetched and converted to base64 by CLI)
+export interface ImageUrlContent {
+  mediaType: 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp';
+  url: string; // S3 or public URL to fetch
+}
+
+// Union type for image input - supports both base64 and URL formats
+export type ImageInput = ImageContent | ImageUrlContent;
+
 // Streaming Event Types (kosuke-cli format)
 export interface StreamingEvent {
   // Event types from kosuke-cli