feat(assistants): Add ability for file upload

[Dark-Sun]

File Attachments Feature Summary

The feature enables automatic detection and upload of files when chatting with CodeMie assistants through two distinct scenarios.

Usage Scenarios

Scenario 1: Auto-Detection (Images Only)

Use Case: User attaches images in Claude Code session, assistant automatically detects and uploads them

Workflow:

1. In Claude Code CLI, user attaches an image

   • Example: User sends screenshot → Claude shows [Image: source: /path/to/screenshot.png]

2. User invokes assistant chat:

   codemie assistant chat <assistant-id> --conversation-id <conv-id>

3. System automatically:

   • Detects base64-encoded images from Claude session JSONL (last 2 user messages)
   • Extracts image data + metadata (filename, media type, size)
   • Uploads images to CodeMie platform
   • Passes image URLs to assistant API

Note: Currently Claude Code only attaches images (screenshots, PNG, JPG, etc.), so auto-detection primarily handles images.

Primary Use: Screenshots and images during coding workflows

Scenario 2: Manual File Paths (All File Types)

Use Case: User drags files (PDFs, documents, images) into the terminal prompt and file paths are present

Workflow:

1. User drags files into terminal prompt:

   codemie assistant chat <id> --file ./report.pdf --file ./chart.png --file ./data.csv

2. System processes file paths:

   • Validates file existence and size (100 MB limit)
   • Reads file content and detects media type (mime-types)
   • Uploads files to CodeMie platform
   • Passes file URLs to assistant API

Supported: Any file type (PDFs, documents, spreadsheets, images, etc.)

Primary Use: PDFs, documents, data files that need to be shared with assistant

Implementation Details

Scenario 1: Auto-Detection (Images)

Source: Claude session JSONL (~/.codemie/sessions/<session-id>.jsonl)

Detection Flow:

1. Read last 2 user messages from session JSONL
2. Find messages with type: "image" and source.type: "base64"
3. Correlate with meta messages containing file paths: [Image: source: /path]
4. Extract: fileName, base64 data, mediaType, sizeBytes
5. Validate: 100 MB limit, base64 format, path security

Key Commits: b634457, 0f927f7, 8f1fcf7, eba865d

Limitations: Only images (Claude Code limitation)

Scenario 2: Manual File Paths (All Files)

Source: CLI arguments (--file <path>)

Processing Flow:

1. Parse --file flags from CLI arguments
2. Resolve file paths and check existence
3. Read file content with fs.readFileSync()
4. Detect media type with mime-types package
5. Validate: 100 MB limit, file exists, readable
6. Convert to base64 if needed

Key Commit: f1ed570 (added mime-types package + file path support)

Advantages: Works with any file type, not limited to images

Key Differences

Scenario 1: Auto-Detection

• Trigger: Automatic (from Claude session)
• File Types: Images only (Claude Code limitation)
• Source: Session JSONL (base64 data)
• User Action: Attach image in Claude Code
• Detection: Scans last 2 user messages
• Primary Use: Screenshots, images during coding

Scenario 2: Manual File Paths

• Trigger: Manual (--file flag)
• File Types: Any file type
• Source: File system paths
• User Action: Drag file into terminal prompt
• Detection: Parses CLI arguments
• Primary Use: PDFs, documents, data files

Unified Upload Flow (Both Scenarios)

After detection/processing, both scenarios converge:

1. Collect DetectedFile[] from either scenario
2. Bulk upload via CodeMie SDK FileService
3. Get uploaded file URLs from response
4. Pass URLs to assistant chat endpoint
5. Assistant can access/process the files

Security & Validation (Both Scenarios)

• Size limit: 100 MB max per file
• Path security: basename() for auto-detection, resolve() for file paths
• Base64 validation: Try-catch prevents crashes (Scenario 1)
• File existence: Check before read (Scenario 2)
• Sanitized logging: No raw base64/file content in logs
• Media type detection: Automatic via mime-types package

Example Usage

Scenario 1: Auto-detection (images from Claude session)

codemie assistant chat my-assistant --conversation-id abc-123

Result: Automatically uploads images attached in Claude Code

Scenario 2: Manual file paths (any file type)

codemie assistant chat my-assistant --file ./report.pdf --file ./screenshot.png

Result: Uploads specified files from file system

Combined: Both scenarios work together

codemie assistant chat my-assistant --conversation-id abc-123 --file ./report.pdf

Result: Uploads both images from Claude session AND specified PDF file

Key Benefits

Scenario 1 (Auto-Detection)

• Seamless UX (no manual upload)
• Perfect for coding workflows with screenshots
• Works with existing Claude Code sessions

Scenario 2 (Manual Paths)

• Support for all file types (not just images)
• Direct control over which files to upload
• Fast: drag-and-drop workflow

Overall

• Secure with multiple validation layers
• Efficient bulk upload (single API call)
• Production-ready (26+ test cases)
• Fast detection (only last 2 messages scanned)

[Dark-Sun]

@8nevil8 ready for review

[8nevil8]

Code Review — Architecture & Functionality

Overall: The core logic in uploadDetector.ts is well-structured and the test coverage is thorough, but there are 2 critical blockers and 3 major issues that should be addressed before merging.

---

🚨 CRITICAL (Blockers)

1. Architecture Violation — CLI imports directly from Plugin layer

src/cli/commands/assistants/chat/uploadDetector.ts:11 imports ClaudeMessage directly from src/agents/plugins/claude/claude-message-types.ts. The project enforces a strict 5-layer flow: CLI → Registry → Plugin → Core → Utils. CLI must never bypass the Registry and reach into a specific plugin's types.

This creates a hard coupling between the CLI assistants command and the claude plugin, breaking the open/closed principle — adding a Gemini or OpenCode variant would require modifying CLI files.

Fix: Define an agent-agnostic SessionMessage interface in src/agents/core/ and import from there instead.

---

2. Hardcoded Personal Developer Path in User-Generated Files

Both claude-skill-generator.ts:69 and claude-agent-generator.ts:71 embed a personal macOS path (/Users/Andriy_Lukashchuk/Desktop/todo_edit.py) directly in the templates written to end-user systems. Every user running codemie assistants setup will have this path baked into their generated files.

Fix: Replace with a generic placeholder, e.g. ./my-script.py.

---

⚠️ MAJOR

3. Files re-uploaded on every interactive turn (chat/index.ts:195–232)

detectedFiles is passed to sendMessageWithHistory inside the while(true) loop, causing the same files to be re-uploaded on every message, not just the first one.

Fix: Clear the files after the first send:

let pendingFiles = detectedFiles;
while (true) {
  const response = await sendMessageWithHistory(..., pendingFiles);
  pendingFiles = []; // clear after first send
}

---

4. Silent save_history: false behavior change (chat/index.ts:362)

save_history: false was added to the chat API call with no explanation or PR description context. If the server default was true, this silently disables history persistence for all users of the assistant chat command.

Fix: Either add a comment explaining the intent (e.g., "history is managed client-side via JSONL") or remove if accidental.

---

5. console.log not guarded by quiet flag in error paths (uploadDetector.ts:308, 316, 328, 358)

File validation warnings (file not found, not a file, too large, read failure) always print to stdout regardless of the quiet option. In single-message mode (used by Claude Code skills), this will corrupt the response that Claude Code reads back.

Fix: Wrap all error-path console.log calls:

if (!quiet) {
  console.log(chalk.yellow(`⚠ File not found: ${filePath}`));
}

---

✅ Positives

• uploadDetector.ts is well-decomposed with single-responsibility helper functions
• Extensive test coverage (26+ cases) including error paths and quiet-mode contract
• Correct Commander.js --file collector pattern for multiple values
• Good reuse of the existing readJSONL core utility
• The interactive-prompt.ts space-in-search-box fix is a solid UX improvement

[8nevil8]

Code Review Follow-up — Comment Resolution Status

3 of 5 issues were addressed. The 2 blockers from the previous review are summarized below.

---

🚨 Still Open (Blockers)

1. Architecture Violation — CLI still imports directly from Plugin layer

claudeUploadsDetector.ts:14 still has:

import type { ClaudeMessage } from '@/agents/plugins/claude/claude-message-types.js';

No SessionMessage interface was added to src/agents/core/ in this PR. The coupling between the CLI assistants command and the claude plugin remains. Not addressed.

---

2. save_history: false — still no explanation

chat/index.ts:362 adds save_history: false to the API call with no comment. The review asked for either a comment explaining intent (e.g., history is managed client-side via JSONL) or removal if accidental. Neither was done. Not addressed.

---

✅ Addressed

3. Files re-uploaded on every turn — fixed correctly with pendingFiles = [] after first send in the interactive loop.

4. Hardcoded personal developer path — /Users/Andriy_Lukashchuk/Desktop/todo_edit.py removed from both generators; replaced with generic placeholders.

5. console.log not guarded by quiet flag — all four error-path console.log calls in readFilesFromPaths are now wrapped with if (!quiet).