feat: link agent-uploaded files to thread response messages

When an agent uploads files via workspace_write_file MCP tool, those
files now appear as attachments on the agent's response message in the
thread UI. Previously files only appeared in the Files panel.

Changes:
- Base adapter: track uploaded files per channel, attach on _send_response()
- Claude adapter: query for uploaded files before sending final response
- Backend: add channel_name/uploaded_by filters to GET /v1/files
- Frontend: expand isPreviewable() to include markdown, text, and code files

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: baryhuang

docs/guides/artifact-panel-file-return.md

@@ -1,156 +1,52 @@
-# Feature: Artifact Panel & Agent File Return
+# Feature: Agent File Return in Thread Messages
 
 ## Problem Statement
 
-The workspace thread UI currently has two gaps in file handling:
+When an agent uploads a file to the workspace (via `workspace_write_file` MCP tool), the file appears in the Files panel but is **not linked to the agent's chat response message**. The file upload and the response message are completely disconnected events.
 
-1. **Agents don't return files in thread messages.** When an agent generates content (markdown documents, code files, HTML), it dumps everything into `payload.content` as inline text. The plumbing for file attachments exists end-to-end (SDK → backend → frontend), but nothing in the agent orchestration layer creates files and attaches them to responses.
+Additionally, the thread UI only treats images and HTML as previewable — markdown, code, and text files show as plain download links.
 
-2. **No artifact/canvas side panel.** When a file attachment does exist on a message, clicking it navigates away from the chat (`setViewMode('files')`). There is no way to view a file alongside the conversation, unlike Claude Desktop's artifact panel.
+## What Was Implemented
 
-## Current Architecture
+### 1. File tracking in base adapter (`sdk/src/openagents/adapters/base.py`)
 
-### How thread messages work (end-to-end)
+- Added `_channel_uploaded_files` dict to track files uploaded during message handling
+- Added `track_uploaded_file(channel, file_info)` method
+- Modified `_send_response()` to pop tracked files and pass them as `attachments` to `client.send_message()`
 
-```
-User sends message
-  → ChatInput → workspaceApi.sendMessage()
-  → POST /v1/events { type: "workspace.message.posted", source: "human:user" }
-  → Backend Pipeline:
-      1. AuthMod (verify token)
-      2. WorkspaceMod (route: parse @mentions, LLM router picks target agent)
-      3. PersistenceMod (save EventRecord to DB)
-  → Agent polls GET /v1/events (every ~1s via AgentRunner._async_loop)
-  → react() → orchestrate_agent() → LLM + tools
-  → Agent posts response: WorkspaceClient.send_message()
-  → POST /v1/events { type: "workspace.message.posted", source: "openagents:agent-name" }
-  → Same pipeline → persisted to DB
-  → Frontend polls GET /v1/events?after={cursor} (every 2s)
-  → eventToMessage() → renders in chat via ChatMessage component
-```
-
-### How file uploads work
-
-**User upload (works today):**
-1. Upload file → `POST /v1/files` (multipart) → returns `{ id, filename, contentType, size }`
-2. Message event includes `payload.attachments: [{ fileId, filename, contentType, url }]`
-3. Frontend `Attachments` component renders attachment in thread
-4. URL regenerated from `fileId` at render time via `workspaceApi.getFileUrl(fileId)`
-
-**Agent upload (plumbing exists, unused):**
-1. `POST /v1/files/base64` — JSON endpoint designed for agents (base64-encoded content)
-2. Returns same `{ id, filename, contentType, size }`
-3. `WorkspaceClient.send_message()` accepts `attachments` parameter — never called with it
-4. Agent orchestrator puts all output in `payload.content` as plain text
-
-### Message attachment structure
-
-```typescript
-// In event payload
-payload: {
-  content: "Here's the report",
-  attachments: [
-    { fileId: "uuid", filename: "report.md", contentType: "text/markdown", url: "..." }
-  ]
-}
-
-// Extracted into message
-message.metadata.attachments = [{ fileId, filename, contentType, url }]
-```
-
-### Thread UI attachment rendering (chat-message.tsx)
-
-- **Images**: inline thumbnail, click → navigates to files view
-- **HTML files**: eye icon button, click → navigates to files view
-- **Other files**: download link (`<a href={url}>`)
-- **Markdown**: not treated as previewable (only images and HTML pass `isPreviewable()`)
-
-### Files view (file-preview.tsx)
-
-Full-page preview supporting HTML (iframe), images, markdown (MarkdownContent), text/code (pre block). Replaces the chat view entirely when `viewMode` switches to `'files'`.
-
-### Existing split panel precedent
-
-The browser view already supports a split mode: chat on left + browser on right (50/50). This is toggled via `splitBrowser` state in `LayoutContext` and persisted to localStorage.
-
-## Identified Gaps
+### 2. File collection in Claude adapter (`sdk/src/openagents/adapters/claude.py`)
 
-| Gap | Current State | What's Needed |
-|-----|--------------|---------------|
-| Agent file creation | Agent can upload via `/v1/files/base64` but never does | Agent orchestrator should upload generated files and attach metadata to response events |
-| Markdown not previewable in threads | `isPreviewable()` only returns true for images and HTML | Add markdown, code, SVG to previewable types |
-| No side panel for artifacts | Clicking attachment navigates away from chat to files view | Add split artifact panel alongside chat (reuse browser split pattern) |
-| No inline artifact detection | Long code/markdown blocks live inside message content | Detect fenced code blocks and offer "Open in panel" action |
-| File preview is full-page only | `file-preview.tsx` replaces chat entirely | Need a panel-mode variant that coexists with chat |
+- Added `_collect_uploaded_files(channel)` method that queries `GET /v1/files` for files uploaded by this agent to this channel
+- Tracks already-attached file IDs in `_attached_file_ids` to avoid duplicates across responses
+- Called before sending the final response
 
-## Implementation Plan
+### 3. Backend: filter support for file listing (`workspace/backend/app/routers/files.py`)
 
-### Phase 1: Agent File Return (Backend/SDK)
+- Added optional `channel_name` and `uploaded_by` query params to `GET /v1/files`
+- Updated `workspace_client.list_files()` to pass these filters
 
-**Goal:** When an agent generates substantial content, upload it as a file and attach to the response message.
+### 4. Frontend: expanded previewable types (`chat-message.tsx`)
 
-Key files:
-- `sdk/src/openagents/agents/runner.py` — agent orchestration loop
-- `sdk/src/openagents/client/workspace_client.py` — `send_message()` and file upload methods
+- `isPreviewable()` now returns true for markdown, text, and common code file types
+- Affected files: `packages/go/` and `workspace/frontend/` (kept in sync)
 
-Changes:
-- In the agent orchestration layer, after LLM generates a response, detect substantial content blocks (markdown docs, code files, HTML)
-- Upload via `POST /v1/files/base64` with `source: "openagents:{agent-name}"`
-- Include attachment metadata in the `send_message()` call
-- Keep the inline `content` as a summary/reference, not the full file
+## Architecture (unchanged)
 
-### Phase 2: Artifact Side Panel (Frontend)
-
-**Goal:** View files alongside the conversation, like Claude Desktop's artifact panel.
-
-Key files:
-- `workspace/frontend/components/layout/layout-context.tsx` — add `splitArtifact` state
-- `workspace/frontend/components/layout/wrapper.tsx` — add split layout variant
-- `workspace/frontend/components/chat/chat-message.tsx` — open attachments in panel instead of navigating away
-- New: `workspace/frontend/components/artifacts/artifact-panel.tsx` — panel component
-
-Changes:
-- Add `artifactPanel: { fileId: string } | null` state to LayoutContext
-- Reuse the existing 50/50 split pattern from `splitBrowser`
-- When clicking an attachment in a thread message, set `artifactPanel` instead of `setViewMode('files')`
-- Panel renders file content (reuse rendering logic from `file-preview.tsx`)
-
-### Phase 3: Inline Artifact Detection
-
-**Goal:** Detect code fences in agent messages and offer "Open in panel" button.
-
-Key files:
-- `workspace/frontend/components/chat/markdown-content.tsx` — add action buttons to code blocks
-- `workspace/frontend/components/chat/chat-message.tsx` — coordinate with artifact panel
-
-Changes:
-- In MarkdownContent, add an "Open in panel" button on large fenced code blocks
-- Clicking creates a transient artifact (not persisted to files) and opens in side panel
-- Optionally: "Save as file" action to persist to `/v1/files`
-
-### Phase 4: Rich Artifact Features (Future)
-
-- Edit-in-panel for markdown/code
-- Version history (multiple iterations of same artifact)
-- Mermaid diagram rendering
-- Live-updating artifacts (agent streams, panel updates)
+```
+Agent uses workspace_write_file MCP tool
+  → POST /v1/files/base64 (uploads file)
+  → File appears in Files panel
+
+Agent finishes processing
+  → _collect_uploaded_files() queries GET /v1/files?channel_name=X&uploaded_by=openagents:Y
+  → Files tracked via track_uploaded_file()
+  → _send_response() includes attachments in message event
+  → Frontend renders attachments in thread with eye icon (previewable)
+  → Click opens file preview (navigates to files view)
+```
 
-## Key Files Reference
+## Future Work
 
-| File | Role |
-|------|------|
-| `workspace/frontend/components/chat/chat-message.tsx` | Thread message + attachment rendering |
-| `workspace/frontend/components/chat/chat-input.tsx` | Message composition + file upload |
-| `workspace/frontend/components/chat/chat-view.tsx` | Main chat view, handles send flow |
-| `workspace/frontend/components/chat/markdown-content.tsx` | Markdown rendering in messages |
-| `workspace/frontend/components/files/file-preview.tsx` | Full-page file preview |
-| `workspace/frontend/components/layout/layout-context.tsx` | UI state (viewMode, splitBrowser) |
-| `workspace/frontend/components/layout/wrapper.tsx` | Layout orchestrator |
-| `workspace/frontend/hooks/use-polling.ts` | Message polling |
-| `workspace/frontend/lib/api.ts` | API client (sendMessage, uploadFile, getFileUrl) |
-| `workspace/frontend/lib/types.ts` | Types + eventToMessage conversion |
-| `workspace/backend/app/routers/files.py` | File upload/download/list endpoints |
-| `workspace/backend/app/routers/events.py` | Event posting + polling endpoints |
-| `workspace/backend/app/mods/workspace_mod.py` | Message routing (LLM router) |
-| `sdk/src/openagents/agents/runner.py` | Agent loop + orchestration |
-| `sdk/src/openagents/client/workspace_client.py` | Agent-side API client |
+- **Artifact side panel**: View files alongside the conversation (canvas-like, reuse browser split pattern)
+- **Inline artifact detection**: Detect large code blocks in message content and offer "Open in panel"
+- **Orchestrator path**: `SimpleAutoAgent` still doesn't send response messages — separate issue

packages/go/components/chat/chat-message.tsx

@@ -22,6 +22,8 @@ interface Attachment {
 function isPreviewable(contentType: string, filename: string): boolean {
   if (contentType?.startsWith('image/')) return true;
   if (contentType === 'text/html' || /\.html?$/i.test(filename)) return true;
+  if (contentType === 'text/markdown' || /\.mdx?$/i.test(filename)) return true;
+  if (contentType?.startsWith('text/') || /\.(json|js|ts|tsx|jsx|py|rs|go|java|rb|sh|yaml|yml)$/i.test(filename)) return true;
   return false;
 }
 

sdk/src/openagents/adapters/base.py

@@ -51,6 +51,9 @@ def __init__(
         # Per-channel task tracking for parallel execution
         self._channel_tasks: dict[str, asyncio.Task] = {}
         self._channel_queues: dict[str, list[dict]] = {}
+        # Per-channel uploaded file tracking — files uploaded during message
+        # handling are attached to the final response message.
+        self._channel_uploaded_files: dict[str, list[dict]] = {}
 
     # ------------------------------------------------------------------
     # Lifecycle
@@ -310,15 +313,26 @@ async def _send_status(self, channel: str, content: str):
         except Exception:
             pass
 
+    def track_uploaded_file(self, channel: str, file_info: dict):
+        """Track a file uploaded during message handling for later attachment.
+
+        Args:
+            channel: Channel name where the file was uploaded.
+            file_info: Dict with at least ``fileId``, ``filename``, ``contentType``.
+        """
+        self._channel_uploaded_files.setdefault(channel, []).append(file_info)
+
     async def _send_response(self, channel: str, content: str):
-        """Send a chat response to a channel."""
+        """Send a chat response to a channel, attaching any tracked files."""
+        attachments = self._channel_uploaded_files.pop(channel, None)
         await self.client.send_message(
             workspace_id=self.workspace_id,
             channel_name=channel,
             token=self.token,
             content=content,
             sender_type="agent",
             sender_name=self.agent_name,
+            attachments=attachments or None,
         )
 
     async def _send_error(self, channel: str, error: str):

sdk/src/openagents/adapters/claude.py

@@ -48,6 +48,7 @@ def __init__(
         self._channel_sessions: dict[str, str] = {}  # channel_name → Claude CLI session_id
         self._current_process: Optional[asyncio.subprocess.Process] = None
         self._channel_processes: dict[str, asyncio.subprocess.Process] = {}  # channel → subprocess
+        self._attached_file_ids: set[str] = set()  # files already attached to responses
         self._sessions_file = (
             Path.home() / ".openagents" / "sessions"
             / f"{workspace_id}_{agent_name}.json"
@@ -127,6 +128,33 @@ async def _stop_current_process(self):
             except Exception:
                 pass
 
+    async def _collect_uploaded_files(self, channel: str):
+        """Query for files uploaded by this agent to the channel and track them."""
+        try:
+            result = await self.client.list_files(
+                workspace_id=self.workspace_id,
+                token=self.token,
+                channel_name=channel,
+                uploaded_by=f"openagents:{self.agent_name}",
+                limit=20,
+            )
+            files = result.get("files", [])
+            for f in files:
+                file_id = f.get("id")
+                if not file_id:
+                    continue
+                # Skip files already attached in previous responses
+                if file_id in self._attached_file_ids:
+                    continue
+                self._attached_file_ids.add(file_id)
+                self.track_uploaded_file(channel, {
+                    "fileId": file_id,
+                    "filename": f.get("filename", ""),
+                    "contentType": f.get("content_type", "application/octet-stream"),
+                })
+        except Exception as e:
+            logger.debug(f"Failed to collect uploaded files for channel {channel}: {e}")
+
     def _build_claude_cmd(self, prompt: str, channel_name: str) -> list[str]:
         """Build the claude CLI command for a specific channel."""
         # On Windows, prefer .cmd/.exe wrappers over bare npm bash shims
@@ -524,6 +552,10 @@ async def _handle_message(self, msg: dict):
                 if stderr_text:
                     logger.warning(f"CLI stderr: {stderr_text[:300]}")
 
+            # Collect files uploaded by this agent during processing
+            # and attach them to the final response message.
+            await self._collect_uploaded_files(msg_channel)
+
             # Post the final response.  last_response_text holds text
             # from the last assistant turn (after all tool calls).
             # If posted_thinking is True, the last text was already

sdk/src/openagents/client/workspace_client.py

@@ -604,6 +604,8 @@ async def list_files(
         token: str,
         limit: int = 50,
         offset: int = 0,
+        channel_name: Optional[str] = None,
+        uploaded_by: Optional[str] = None,
     ) -> dict:
         """List files via GET /v1/files."""
         import aiohttp
@@ -612,6 +614,10 @@ async def list_files(
             "limit": limit,
             "offset": offset,
         }
+        if channel_name:
+            params["channel_name"] = channel_name
+        if uploaded_by:
+            params["uploaded_by"] = uploaded_by
         async with aiohttp.ClientSession() as session:
             async with session.get(
                 f"{self.endpoint}/v1/files",

workspace/backend/app/routers/files.py

@@ -223,6 +223,8 @@ async def upload_file_base64(
 async def list_files(
     network: str = Query(..., description="Network (workspace) ID or slug"),
     status: str = Query("active", description="Filter by status"),
+    channel_name: Optional[str] = Query(None, description="Filter by channel name"),
+    uploaded_by: Optional[str] = Query(None, description="Filter by uploader (e.g. openagents:agent-name)"),
     limit: int = Query(50, ge=1, le=200),
     offset: int = Query(0, ge=0),
     x_workspace_token: Optional[str] = Header(None),
@@ -241,10 +243,12 @@ async def list_files(
         select(FileRecord)
         .where(FileRecord.workspace_id == str(workspace.id))
         .where(FileRecord.status == status)
-        .order_by(FileRecord.created_at.desc())
-        .offset(offset)
-        .limit(limit)
     )
+    if channel_name:
+        query = query.where(FileRecord.channel_name == channel_name)
+    if uploaded_by:
+        query = query.where(FileRecord.uploaded_by == uploaded_by)
+    query = query.order_by(FileRecord.created_at.desc()).offset(offset).limit(limit)
     rows = db.execute(query).scalars().all()
 
     total = db.execute(

workspace/frontend/components/chat/chat-message.tsx

@@ -22,6 +22,8 @@ interface Attachment {
 function isPreviewable(contentType: string, filename: string): boolean {
   if (contentType?.startsWith('image/')) return true;
   if (contentType === 'text/html' || /\.html?$/i.test(filename)) return true;
+  if (contentType === 'text/markdown' || /\.mdx?$/i.test(filename)) return true;
+  if (contentType?.startsWith('text/') || /\.(json|js|ts|tsx|jsx|py|rs|go|java|rb|sh|yaml|yml)$/i.test(filename)) return true;
   return false;
 }