@taskforcehq/taskforce 0.3.306 → 0.3.308

package/dist/components/features/AgentsModule.test.js

@@ -5,6 +5,7 @@ import { AgentsModule } from './AgentsModule';
 describe('AgentsModule', () => {
     afterEach(() => {
         vi.restoreAllMocks();
+        vi.unstubAllGlobals();
     });
     it('groups registered AI profiles by surface type in a stable section order', async () => {
         const fetchMock = vi.fn()
@@ -90,12 +91,11 @@ describe('AgentsModule', () => {
         await waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1));
         expect((await screen.findAllByText('Chat Apps')).length).toBeGreaterThan(0);
         expect(screen.getAllByText('Coding Tools').length).toBeGreaterThan(0);
-        expect(screen.getByText('Unclassified')).toBeInTheDocument();
+        expect(screen.getAllByText('Unclassified').length).toBeGreaterThan(0);
         expect(screen.getAllByText('Codex')).toHaveLength(1);
-        expect(screen.getByText(/2 duplicates/i)).toBeInTheDocument();
-        expect(screen.getByText('Coding tool')).toBeInTheDocument();
-        expect(screen.getAllByText('Cloud MCP').length).toBeGreaterThan(0);
-        expect(screen.getAllByText('Local MCP').length).toBeGreaterThan(0);
+        expect(screen.getByText(/1 duplicate/i)).toBeInTheDocument();
+        expect(screen.getAllByTitle('Cloud MCP').length).toBeGreaterThan(0);
+        expect(screen.getAllByTitle('Local MCP').length).toBeGreaterThan(0);
         expect(screen.getByText('Registered Cloud Agents: 2/5')).toBeInTheDocument();
         expect(screen.getAllByText('General-purpose chat surface for planning and writing.').length).toBeGreaterThan(0);
         expect(screen.getAllByText('Product copilot').length).toBeGreaterThan(0);
@@ -107,6 +107,7 @@ describe('AgentsModule', () => {
         expect(text.indexOf('Chat Apps')).toBeLessThan(text.indexOf('Coding Tools'));
         expect(text.indexOf('Coding Tools')).toBeLessThan(text.indexOf('Unclassified'));
         fireEvent.click(screen.getByRole('button', { name: /codex/i }));
+        expect(screen.getByText('Coding Tool')).toBeInTheDocument();
         expect(screen.getAllByText('Terminal-first coding agent.').length).toBeGreaterThan(0);
         expect(screen.getAllByText('Implementation partner')[0]).toBeInTheDocument();
         expect(screen.getAllByText('OpenAI').length).toBeGreaterThan(0);
@@ -119,6 +120,191 @@ describe('AgentsModule', () => {
         expect(screen.getAllByTitle('Cloud MCP').length).toBeGreaterThan(0);
         expect(screen.getAllByTitle('Local MCP').length).toBeGreaterThan(0);
     });
+    it('does not mark local and cloud profiles with the same name as duplicates', async () => {
+        const fetchMock = vi.fn()
+            .mockResolvedValueOnce({
+            ok: true,
+            json: async () => ({
+                aiProfileSeatUsage: {
+                    used: 1,
+                    limit: null,
+                    remaining: null
+                },
+                assignees: [
+                    {
+                        value: 'ai-codex-local',
+                        label: 'Codex',
+                        username: 'codex',
+                        icon: 'Bot',
+                        color: '#0ea5e9',
+                        kind: 'agent',
+                        surfaceType: 'cli',
+                        seatScope: 'local_unmetered',
+                        description: 'Terminal-first coding agent.',
+                        role: 'Coding Agent',
+                        provider: 'OpenAI',
+                        model: 'Codex',
+                        createdAt: '2026-04-02T09:00:00.000Z',
+                        updatedAt: '2026-04-04T13:15:00.000Z',
+                        lastActiveAt: '2026-04-04T13:45:00.000Z'
+                    },
+                    {
+                        value: 'ai-codex-cloud',
+                        label: 'Codex',
+                        username: 'codex',
+                        icon: 'Bot',
+                        color: '#0ea5e9',
+                        kind: 'agent',
+                        surfaceType: 'cli',
+                        seatScope: 'cloud_metered',
+                        description: 'Cloud MCP coding profile.',
+                        role: 'Coding Agent',
+                        provider: 'OpenAI',
+                        model: 'Codex',
+                        createdAt: '2026-04-02T10:00:00.000Z',
+                        updatedAt: '2026-04-04T13:16:00.000Z',
+                        lastActiveAt: '2026-04-04T13:46:00.000Z'
+                    }
+                ]
+            })
+        });
+        vi.stubGlobal('fetch', fetchMock);
+        render(_jsx(AgentsModule, { workspaceId: "workspace-1", cloudAuthConfigured: true, authSessionResolved: true, isAuthenticated: true, cloudAiProfileSeatUsage: { used: 1, limit: 5, remaining: 4 } }));
+        await waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1));
+        expect(screen.getAllByRole('button', { name: /codex/i })).toHaveLength(2);
+        expect(screen.queryByText(/\d+ duplicate/i)).not.toBeInTheDocument();
+        expect(screen.queryByText(/Profile instances/i)).not.toBeInTheDocument();
+        expect(screen.getAllByTitle('Cloud MCP').length).toBeGreaterThan(0);
+        expect(screen.getAllByTitle('Local MCP').length).toBeGreaterThan(0);
+    });
+    it('keeps a duplicate group avatar visible when the newest duplicate has no photo', async () => {
+        const avatarUrl = '/api/taskforce/context/workspaces%2Fworkspace-1%2Fassets%2Fimages%2Fai-profiles%2Fai-codex-old%2Favatar%2Fcropped.webp';
+        const fetchMock = vi.fn()
+            .mockResolvedValueOnce({
+            ok: true,
+            json: async () => ({
+                aiProfileSeatUsage: {
+                    used: 2,
+                    limit: null,
+                    remaining: null
+                },
+                assignees: [
+                    {
+                        value: 'ai-codex-new',
+                        label: 'Codex',
+                        username: 'codex-new',
+                        icon: 'Bot',
+                        color: '#0ea5e9',
+                        kind: 'agent',
+                        surfaceType: 'coding_tool',
+                        seatScope: 'local_unmetered',
+                        createdAt: '2026-04-02T10:00:00.000Z',
+                        updatedAt: '2026-04-04T16:00:00.000Z',
+                        lastActiveAt: '2026-04-04T16:30:00.000Z',
+                        avatarUrl: null,
+                        avatarSourceUrl: null
+                    },
+                    {
+                        value: 'ai-codex-old',
+                        label: 'Codex',
+                        username: 'codex-old',
+                        icon: 'Bot',
+                        color: '#0ea5e9',
+                        kind: 'agent',
+                        surfaceType: 'coding_tool',
+                        seatScope: 'local_unmetered',
+                        createdAt: '2026-04-02T09:00:00.000Z',
+                        updatedAt: '2026-04-04T13:15:00.000Z',
+                        lastActiveAt: '2026-04-04T13:45:00.000Z',
+                        avatarUrl,
+                        avatarSourceUrl: avatarUrl
+                    }
+                ]
+            })
+        });
+        vi.stubGlobal('fetch', fetchMock);
+        render(_jsx(AgentsModule, { workspaceId: "workspace-1", cloudAuthConfigured: true, authSessionResolved: true, isAuthenticated: true, cloudAiProfileSeatUsage: { used: 2, limit: 5, remaining: 3 } }));
+        const codexButton = await screen.findByRole('button', { name: /codex/i });
+        expect(codexButton.querySelector('img')).toHaveAttribute('src', avatarUrl);
+        expect(screen.getByLabelText('Edit AI profile photo').querySelector('img')).toHaveAttribute('src', avatarUrl);
+    });
+    it('uploads AI profile avatars through the stable avatar endpoint', async () => {
+        const avatarUrl = '/api/taskforce/context/workspaces%2Fworkspace-1%2Fassets%2Fimages%2Fai-profiles%2Fai-codex%2Favatar%2Fdisplay.gif';
+        const fetchMock = vi.fn(async (input, init) => {
+            const url = String(input);
+            if (url.startsWith('/api/taskforce/workspace/assignee-options')) {
+                return {
+                    ok: true,
+                    json: async () => ({
+                        aiProfileSeatUsage: {
+                            used: 1,
+                            limit: null,
+                            remaining: null
+                        },
+                        assignees: [
+                            {
+                                value: 'ai-codex',
+                                label: 'Codex',
+                                username: 'codex',
+                                icon: 'Bot',
+                                color: '#0ea5e9',
+                                kind: 'agent',
+                                surfaceType: 'coding_tool',
+                                seatScope: 'cloud_metered',
+                                createdAt: '2026-04-02T09:00:00.000Z',
+                                updatedAt: '2026-04-04T13:15:00.000Z',
+                                lastActiveAt: '2026-04-04T13:45:00.000Z',
+                                avatarUrl: null,
+                                avatarSourceUrl: null
+                            }
+                        ]
+                    })
+                };
+            }
+            if (url === '/api/taskforce/workspace/ai-profiles/avatar/upload') {
+                return {
+                    ok: true,
+                    json: async () => ({
+                        profile: {
+                            id: 'ai-codex',
+                            avatarUrl,
+                            avatarSourceUrl: '/api/taskforce/context/workspaces%2Fworkspace-1%2Fassets%2Fimages%2Fai-profiles%2Fai-codex%2Favatar%2Fsource.gif',
+                            avatarRevision: 1,
+                            avatarUpdatedAt: '2026-04-28T00:00:00.000Z'
+                        }
+                    })
+                };
+            }
+            throw new Error(`Unexpected fetch ${url}: ${String(init?.body || '')}`);
+        });
+        vi.stubGlobal('fetch', fetchMock);
+        vi.stubGlobal('URL', {
+            ...URL,
+            createObjectURL: vi.fn(() => 'blob:avatar-preview'),
+            revokeObjectURL: vi.fn()
+        });
+        render(_jsx(AgentsModule, { workspaceId: "workspace-1", cloudAuthConfigured: true, authSessionResolved: true, isAuthenticated: true, cloudAiProfileSeatUsage: { used: 1, limit: 5, remaining: 4 } }));
+        fireEvent.click(await screen.findByLabelText('Edit AI profile photo'));
+        const input = await screen.findByLabelText('Choose profile photo');
+        const file = new File(['avatar'], 'avatar.gif', { type: 'image/gif' });
+        fireEvent.change(input, { target: { files: [file] } });
+        fireEvent.click(screen.getByRole('button', { name: 'Apply Photo' }));
+        await waitFor(() => {
+            expect(fetchMock).toHaveBeenCalledWith('/api/taskforce/workspace/ai-profiles/avatar/upload', expect.objectContaining({ method: 'POST' }));
+        });
+        const uploadBody = JSON.parse(String(fetchMock.mock.calls.find((call) => call[0] === '/api/taskforce/workspace/ai-profiles/avatar/upload')?.[1]?.body || '{}'));
+        expect(uploadBody).toEqual(expect.objectContaining({
+            profileId: 'ai-codex',
+            displayImage: expect.objectContaining({
+                mimeType: 'image/gif',
+                originalName: 'avatar.gif'
+            })
+        }));
+        expect(String(uploadBody.displayImage.dataUrl)).toMatch(new RegExp('^data:image/gif;base64,'));
+        expect(fetchMock.mock.calls.some((call) => call[0] === '/api/taskforce/context-upload/init')).toBe(false);
+        expect(fetchMock.mock.calls.some((call) => call[0] === '/api/taskforce/context-upload/finalize')).toBe(false);
+        expect(fetchMock.mock.calls.some((call) => call[0] === '/api/taskforce/context-upload' && String(call[1]?.method || '').toUpperCase() === 'POST')).toBe(false);
+    });
     it('removes a profile from the active roster and reloads the list', async () => {
         const confirmMock = vi.fn().mockReturnValue(true);
         const fetchMock = vi.fn()
@@ -174,19 +360,83 @@ describe('AgentsModule', () => {
         vi.stubGlobal('confirm', confirmMock);
         render(_jsx(AgentsModule, { workspaceId: "workspace-1", cloudAuthConfigured: true, authSessionResolved: true, isAuthenticated: true, cloudAiProfileSeatUsage: { used: 1, limit: 3, remaining: 2 } }));
         expect(await screen.findByRole('button', { name: /codex/i })).toBeInTheDocument();
-        fireEvent.click(screen.getByRole('button', { name: /remove from roster/i }));
+        fireEvent.change(screen.getByLabelText('Agent roster status'), { target: { value: 'retire' } });
         await waitFor(() => expect(confirmMock).toHaveBeenCalledTimes(1));
         expect(fetchMock).toHaveBeenNthCalledWith(2, '/api/taskforce/workspace/ai-profiles/archive', expect.objectContaining({
             method: 'POST',
             credentials: 'include'
         }));
-        expect(fetchMock).toHaveBeenNthCalledWith(3, '/api/taskforce/workspace/assignee-options?workspaceId=workspace-1', expect.objectContaining({
+        expect(fetchMock).toHaveBeenNthCalledWith(3, '/api/taskforce/workspace/assignee-options?workspaceId=workspace-1&kind=agent', expect.objectContaining({
             credentials: 'include'
         }));
         expect(await screen.findByText('AI profile removed from active roster.')).toBeInTheDocument();
         expect(await screen.findByText('No AI profiles registered yet.')).toBeInTheDocument();
     });
-    it('shows archive permission errors inline above the remove button', async () => {
+    it('updates an AI profile category from the detail dropdown', async () => {
+        const fetchMock = vi.fn(async (input, init) => {
+            const url = String(input);
+            if (url.startsWith('/api/taskforce/workspace/assignee-options')) {
+                return {
+                    ok: true,
+                    json: async () => ({
+                        aiProfileSeatUsage: {
+                            used: 1,
+                            limit: null,
+                            remaining: null
+                        },
+                        assignees: [
+                            {
+                                value: 'ai-chatgpt',
+                                label: 'ChatGPT',
+                                username: 'chatgpt',
+                                icon: 'Bot',
+                                color: '#10a37f',
+                                kind: 'agent',
+                                surfaceType: 'chat_app',
+                                seatScope: 'cloud_metered',
+                                provider: 'OpenAI',
+                                model: 'GPT-5',
+                                createdAt: '2026-04-02T09:00:00.000Z',
+                                updatedAt: '2026-04-04T13:15:00.000Z',
+                                lastActiveAt: '2026-04-04T13:45:00.000Z'
+                            }
+                        ]
+                    })
+                };
+            }
+            if (url === '/api/taskforce/workspace/ai-profiles/surface-type') {
+                return {
+                    ok: true,
+                    json: async () => ({
+                        profile: {
+                            id: 'ai-chatgpt',
+                            surfaceType: 'cli',
+                            updatedAt: '2026-04-28T00:00:00.000Z'
+                        }
+                    })
+                };
+            }
+            throw new Error(`Unexpected fetch ${url}: ${String(init?.body || '')}`);
+        });
+        vi.stubGlobal('fetch', fetchMock);
+        render(_jsx(AgentsModule, { workspaceId: "workspace-1", cloudAuthConfigured: true, authSessionResolved: true, isAuthenticated: true, cloudAiProfileSeatUsage: { used: 1, limit: 3, remaining: 2 } }));
+        const categorySelect = await screen.findByLabelText('Agent category');
+        fireEvent.change(categorySelect, { target: { value: 'cli' } });
+        await waitFor(() => {
+            expect(fetchMock).toHaveBeenCalledWith('/api/taskforce/workspace/ai-profiles/surface-type', expect.objectContaining({
+                method: 'POST',
+                credentials: 'include',
+                body: JSON.stringify({
+                    profileId: 'ai-chatgpt',
+                    surfaceType: 'cli'
+                })
+            }));
+        });
+        expect(await screen.findByText('AI profile category updated.')).toBeInTheDocument();
+        expect(screen.getByLabelText('Agent category').value).toBe('cli');
+        expect(screen.getAllByText('CLI').length).toBeGreaterThan(0);
+    });
+    it('shows archive permission errors inline near the roster status control', async () => {
         const confirmMock = vi.fn().mockReturnValue(true);
         const fetchMock = vi.fn()
             .mockResolvedValueOnce({
@@ -227,11 +477,10 @@ describe('AgentsModule', () => {
         vi.stubGlobal('confirm', confirmMock);
         render(_jsx(AgentsModule, { workspaceId: "workspace-1", cloudAuthConfigured: true, authSessionResolved: true, isAuthenticated: true, cloudAiProfileSeatUsage: { used: 1, limit: 3, remaining: 2 } }));
         expect(await screen.findByRole('button', { name: /codex/i })).toBeInTheDocument();
-        fireEvent.click(screen.getByRole('button', { name: /remove from roster/i }));
+        fireEvent.change(screen.getByLabelText('Agent roster status'), { target: { value: 'retire' } });
         const inlineError = await screen.findByRole('alert');
         expect(inlineError).toHaveTextContent('Forbidden: owner or admin role required.');
-        const removeButton = screen.getByRole('button', { name: /remove from roster/i });
-        expect(removeButton.compareDocumentPosition(inlineError) & Node.DOCUMENT_POSITION_PRECEDING).toBeTruthy();
+        expect(screen.getByLabelText('Agent roster status')).toBeInTheDocument();
     });
     it('falls back to local seat usage only when cloud auth is not configured', async () => {
         const fetchMock = vi.fn()

package/dist/components/features/AnnotatedAttachmentWorkspace.d.ts

@@ -8,6 +8,8 @@ type ShellProps = {
     requestedTarget?: OpenAnnotatedAttachmentDetail | null;
     requestedSessionId?: string | null;
     requestedOpenVersion?: number;
+    imageTrayOpen?: boolean;
+    onCloseImageTray?: () => void;
     resolveTaskReferenceLabel?: (taskId: string) => string;
     resolveImageReferenceLabel?: (assetId: string) => string;
     onRequestedTargetHandled?: () => void;
@@ -20,5 +22,5 @@ type ShellProps = {
     }) => void;
     onBackToTask?: (taskId: string) => void;
 };
-export declare function AnnotatedAttachmentWorkspaceShell({ runtimeMode, apiBaseUrl, cloudAuthBaseUrl, workspaceId, sessionLoadReady, requestedTarget, requestedSessionId, requestedOpenVersion, resolveTaskReferenceLabel, resolveImageReferenceLabel, onRequestedTargetHandled, onOpenTarget, onContextChange, onBackToTask, }: ShellProps): import("react/jsx-runtime").JSX.Element;
+export declare function AnnotatedAttachmentWorkspaceShell({ runtimeMode, apiBaseUrl, cloudAuthBaseUrl, workspaceId, sessionLoadReady, requestedTarget, requestedSessionId, requestedOpenVersion, imageTrayOpen, onCloseImageTray, resolveTaskReferenceLabel, resolveImageReferenceLabel, onRequestedTargetHandled, onOpenTarget, onContextChange, onBackToTask, }: ShellProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/features/AnnotatedAttachmentWorkspace.js

@@ -1,6 +1,6 @@
-import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { ArrowDown, ArrowLeft, ArrowUpLeft, ArrowUp, Check, ClipboardPaste, Copy, FolderOpen, Hand, HelpCircle, Loader2, MessageSquareCode, MessageSquareText, MousePointer2, Pin, Plus, RotateCcw, Save, SquareMousePointer, Trash2, ZoomIn, ZoomOut, } from 'lucide-react';
+import { ArrowDown, ArrowLeft, ArrowUpLeft, ArrowUp, Check, ChevronLeft, ClipboardPaste, Copy, FolderOpen, Hand, HelpCircle, Loader2, MessageSquareCode, MessageSquareText, MousePointer2, Pin, Plus, RotateCcw, Save, Search, SquareMousePointer, Trash2, ZoomIn, ZoomOut, } from 'lucide-react';
 import sharedStyles from '../../Taskforce.module.css';
 import { fetchTaskforceApi } from '../../utils/taskforceApiClient';
 import { logBootstrapDebug } from '../../hooks/workspace/workspaceLocalState';
@@ -132,6 +132,33 @@ function formatTimestamp(value) {
         return 'Unsaved';
     return parsed.toLocaleString();
 }
+function formatFileSize(bytes) {
+    const normalized = typeof bytes === 'number' && Number.isFinite(bytes) ? Math.max(0, bytes) : 0;
+    if (normalized < 1024)
+        return `${normalized}B`;
+    if (normalized < 1024 * 1024)
+        return `${(normalized / 1024).toFixed(1)}KB`;
+    return `${(normalized / (1024 * 1024)).toFixed(1)}MB`;
+}
+function formatRelativeDate(isoDate) {
+    if (!isoDate)
+        return '';
+    const parsed = new Date(isoDate);
+    if (Number.isNaN(parsed.getTime()))
+        return '';
+    const now = new Date();
+    const diffMs = now.getTime() - parsed.getTime();
+    const diffDays = Math.floor(diffMs / (1000 * 60 * 60 * 24));
+    if (diffDays <= 0)
+        return 'Today';
+    if (diffDays === 1)
+        return 'Yesterday';
+    if (diffDays < 7)
+        return `${diffDays}d ago`;
+    if (diffDays < 30)
+        return `${Math.floor(diffDays / 7)}w ago`;
+    return parsed.toLocaleDateString();
+}
 function getSessionCreatorLabel(session) {
     const createdByLabel = String(session.createdByActor?.label || '').trim();
     if (createdByLabel)
@@ -371,7 +398,7 @@ function buildDraftPayloadFromSession(session, fallbackTitle) {
         annotations: session?.annotations || [],
     });
 }
-export function AnnotatedAttachmentWorkspaceShell({ runtimeMode = 'local', apiBaseUrl = '', cloudAuthBaseUrl = '', workspaceId = 'default', sessionLoadReady = true, requestedTarget = null, requestedSessionId = null, requestedOpenVersion = 0, resolveTaskReferenceLabel, resolveImageReferenceLabel, onRequestedTargetHandled, onOpenTarget, onContextChange, onBackToTask, }) {
+export function AnnotatedAttachmentWorkspaceShell({ runtimeMode = 'local', apiBaseUrl = '', cloudAuthBaseUrl = '', workspaceId = 'default', sessionLoadReady = true, requestedTarget = null, requestedSessionId = null, requestedOpenVersion = 0, imageTrayOpen, onCloseImageTray, resolveTaskReferenceLabel, resolveImageReferenceLabel, onRequestedTargetHandled, onOpenTarget, onContextChange, onBackToTask, }) {
     const resolvedApiBase = runtimeMode === 'cloud'
         ? (cloudAuthBaseUrl || apiBaseUrl || '')
         : '';
@@ -403,6 +430,10 @@ export function AnnotatedAttachmentWorkspaceShell({ runtimeMode = 'local', apiBa
     const [openImageModalOpen, setOpenImageModalOpen] = useState(false);
     const [openImageReference, setOpenImageReference] = useState('');
     const [openingImage, setOpeningImage] = useState(false);
+    const [imageTrayItems, setImageTrayItems] = useState([]);
+    const [imageTraySearchQuery, setImageTraySearchQuery] = useState('');
+    const [imageTrayLoading, setImageTrayLoading] = useState(false);
+    const [imageTrayError, setImageTrayError] = useState(null);
     const [imageLoading, setImageLoading] = useState(false);
     const [imageLoadError, setImageLoadError] = useState(false);
     const [zoomLevel, setZoomLevel] = useState(1);
@@ -486,6 +517,22 @@ export function AnnotatedAttachmentWorkspaceShell({ runtimeMode = 'local', apiBa
         hitRadius: 11,
     }), []);
     const arrowOverlayViewBox = useMemo(() => `0 0 ${Math.max(canvasMediaSize.width, 1)} ${Math.max(canvasMediaSize.height, 1)}`, [canvasMediaSize.height, canvasMediaSize.width]);
+    const showImageTray = typeof imageTrayOpen === 'boolean';
+    const filteredImageTrayItems = useMemo(() => {
+        const query = imageTraySearchQuery.trim().toLowerCase();
+        if (!query)
+            return imageTrayItems;
+        return imageTrayItems.filter((item) => {
+            const haystack = [
+                item.displayName,
+                item.originalFilename,
+                item.imageReferenceLabel,
+                item.taskReferenceLabel,
+                item.assetId,
+            ].filter(Boolean).join(' ').toLowerCase();
+            return haystack.includes(query);
+        });
+    }, [imageTrayItems, imageTraySearchQuery]);
     const canPan = useMemo(() => {
         const scroller = canvasScrollerRef.current;
         if (!scroller)
@@ -889,6 +936,26 @@ export function AnnotatedAttachmentWorkspaceShell({ runtimeMode = 'local', apiBa
             }
         }
     }, [clearPendingAutoSave, createSessionForTarget, requestHeaders, resolvedApiBase, syncDraftFromSession, workspaceId]);
+    const fetchImageTrayItems = useCallback(async () => {
+        setImageTrayLoading(true);
+        setImageTrayError(null);
+        try {
+            const params = new URLSearchParams();
+            params.set('workspaceId', String(workspaceId || 'default').trim() || 'default');
+            const res = await fetchTaskforceApi(`/api/taskforce/annotated-attachments/images?${params.toString()}`, { credentials: 'include', headers: requestHeaders, cache: 'no-store' }, resolvedApiBase);
+            const data = await res.json().catch(() => ({}));
+            if (!res.ok) {
+                throw new Error(String(data?.error || 'Failed to load images.'));
+            }
+            setImageTrayItems(Array.isArray(data?.images) ? data.images : []);
+        }
+        catch (requestError) {
+            setImageTrayError(requestError instanceof Error ? requestError.message : 'Failed to load images.');
+        }
+        finally {
+            setImageTrayLoading(false);
+        }
+    }, [requestHeaders, resolvedApiBase, workspaceId]);
     const pasteImageFromClipboard = useCallback(async () => {
         if (typeof navigator === 'undefined' || !navigator.clipboard || typeof navigator.clipboard.read !== 'function') {
             setError('Clipboard image paste is not supported in this environment.');
@@ -1016,6 +1083,33 @@ export function AnnotatedAttachmentWorkspaceShell({ runtimeMode = 'local', apiBa
             setOpeningImage(false);
         }
     }, [isTargetControlled, loadSessions, onOpenTarget, openImageReference, requestHeaders, workspaceId]);
+    const openImageFromTray = useCallback(async (item) => {
+        if (!item.assetId || !item.path)
+            return;
+        const flushed = await flushPendingDraft('session-switch');
+        if (!flushed)
+            return;
+        const target = {
+            assetId: item.assetId,
+            path: item.path,
+            displayName: String(item.displayName || item.originalFilename || 'Image attachment').trim() || 'Image attachment',
+            ...(item.taskId ? { taskId: item.taskId } : {}),
+            ...(item.taskReferenceLabel ? { taskReferenceLabel: item.taskReferenceLabel } : {}),
+            ...(item.imageReferenceLabel ? { imageReferenceLabel: item.imageReferenceLabel } : {}),
+        };
+        pendingRequestedSessionIdRef.current = null;
+        setError(null);
+        if (isTargetControlled) {
+            lastLoadedTargetKeyRef.current = '';
+            onOpenTarget?.(target, { sessionId: null });
+        }
+        else {
+            setUncontrolledTarget(target);
+            lastLoadedTargetKeyRef.current = getAnnotatedTargetKey(target);
+            resetForTargetLoad(target);
+            void loadSessions(target, { autoCreateIfEmpty: true });
+        }
+    }, [flushPendingDraft, isTargetControlled, loadSessions, onOpenTarget, resetForTargetLoad]);
     const applySessionLocally = useCallback((session) => {
         setSessions((current) => {
             const existingIndex = current.findIndex((item) => item.id === session.id);
@@ -1207,6 +1301,11 @@ export function AnnotatedAttachmentWorkspaceShell({ runtimeMode = 'local', apiBa
         setLastSaveError(null);
         setSaveState('saved');
     }, [currentDraftSnapshot, saveState, selectedSessionId]);
+    useEffect(() => {
+        if (!showImageTray || !imageTrayOpen)
+            return;
+        void fetchImageTrayItems();
+    }, [fetchImageTrayItems, imageTrayOpen, showImageTray]);
     useEffect(() => {
         if (typeof window === 'undefined')
             return undefined;
@@ -1802,7 +1901,22 @@ export function AnnotatedAttachmentWorkspaceShell({ runtimeMode = 'local', apiBa
         event.stopPropagation();
     }, [panMode, readPoint, toolMode]);
     const activeSessionTimestamp = selectedSession?.updatedAt ? formatTimestamp(selectedSession.updatedAt) : 'Not saved yet';
-    return (_jsxs("div", { className: styles.shell, children: [_jsxs("section", { className: `tf-surface-panel ${styles.panel} ${styles.sessionPanel}`, children: [_jsx("div", { className: styles.sessionContextBar, children: activeTarget?.taskId ? (_jsxs(_Fragment, { children: [_jsx("div", { className: styles.sessionContextLeft, children: onBackToTask ? (_jsx("button", { type: "button", className: `tf-button-ghost tf-button-compact ${styles.ghostBtn} ${styles.backToTaskBtn}`, onClick: () => {
+    return (_jsxs("div", { className: `${styles.shell} ${showImageTray ? styles.shellWithImageTray : ''} ${showImageTray && imageTrayOpen ? styles.shellImageTrayOpen : ''}`.trim(), children: [showImageTray ? (_jsxs("aside", { className: `${styles.imageTrayPanel} ${imageTrayOpen ? styles.imageTrayPanelOpen : ''}`.trim(), "aria-label": "Image tray", "aria-hidden": !imageTrayOpen, children: [_jsxs("div", { className: styles.imageTrayHeader, children: [_jsxs("span", { className: styles.imageTrayTitle, children: [_jsx(FolderOpen, { size: 14 }), "Images"] }), _jsx("button", { type: "button", className: "tf-control-icon", onClick: onCloseImageTray, title: "Collapse image tray", "aria-label": "Collapse image tray", children: _jsx(ChevronLeft, { size: 16 }) })] }), _jsxs("div", { className: styles.imageTraySearch, children: [_jsx(Search, { size: 12, className: styles.imageTraySearchIcon }), _jsx("input", { type: "text", placeholder: "Search images...", value: imageTraySearchQuery, onChange: (event) => setImageTraySearchQuery(event.target.value), className: styles.imageTraySearchInput })] }), _jsx("div", { className: `tf-scrollbar ${styles.imageTrayList}`, children: imageTrayLoading ? (_jsx("div", { className: styles.imageTrayState, children: "Loading images..." })) : imageTrayError ? (_jsx("div", { className: styles.imageTrayStateError, children: imageTrayError })) : filteredImageTrayItems.length === 0 ? (_jsx("div", { className: styles.imageTrayState, children: imageTraySearchQuery.trim() ? 'No images match your search.' : 'No images found.' })) : filteredImageTrayItems.map((item) => {
+                            const isSelected = activeTarget?.assetId === item.assetId;
+                            const attachmentCount = typeof item.attachmentCount === 'number' && Number.isFinite(item.attachmentCount)
+                                ? Math.max(0, item.attachmentCount)
+                                : 0;
+                            const sessionCount = typeof item.sessionCount === 'number' && Number.isFinite(item.sessionCount)
+                                ? Math.max(0, item.sessionCount)
+                                : 0;
+                            const linkedLabel = attachmentCount > 1
+                                ? `${attachmentCount} tasks linked`
+                                : attachmentCount === 1
+                                    ? item.taskReferenceLabel || '1 task linked'
+                                    : 'Unattached';
+                            const imageName = String(item.displayName || item.originalFilename || 'Image attachment').trim() || 'Image attachment';
+                            return (_jsxs("button", { type: "button", className: `${styles.imageTrayItem} ${isSelected ? styles.imageTrayItemActive : ''}`.trim(), onClick: () => void openImageFromTray(item), title: imageName, children: [_jsx("span", { className: styles.imageTrayThumb, children: _jsx("img", { src: item.path, alt: "", loading: "lazy" }) }), _jsxs("span", { className: styles.imageTrayItemBody, children: [_jsx("span", { className: styles.imageTrayItemTitle, children: imageName }), _jsx("span", { className: styles.imageTrayItemTask, children: linkedLabel }), _jsxs("span", { className: styles.imageTrayItemMeta, children: [_jsxs("span", { className: styles.imageTrayItemMetaDetails, children: [formatFileSize(item.sizeBytes), item.updatedAt ? _jsxs(_Fragment, { children: [" \u00B7 ", formatRelativeDate(item.updatedAt)] }) : null, sessionCount > 0 ? _jsxs(_Fragment, { children: [" \u00B7 ", sessionCount, " session", sessionCount === 1 ? '' : 's'] }) : null] }), item.imageReferenceLabel ? (_jsx("span", { className: styles.imageTrayItemReference, children: item.imageReferenceLabel })) : null] })] })] }, item.assetId));
+                        }) })] })) : null, _jsxs("section", { className: `tf-surface-panel ${styles.panel} ${styles.sessionPanel}`, children: [_jsx("div", { className: styles.sessionContextBar, children: activeTarget?.taskId ? (_jsxs(_Fragment, { children: [_jsx("div", { className: styles.sessionContextLeft, children: onBackToTask ? (_jsx("button", { type: "button", className: `tf-button-ghost tf-button-compact ${styles.ghostBtn} ${styles.backToTaskBtn}`, onClick: () => {
                                             void flushPendingDraft('back-to-task').then((saved) => {
                                                 if (!saved)
                                                     return;

package/dist/components/features/AnnotatedAttachmentWorkspace.test.js

@@ -320,6 +320,58 @@ describe('AnnotatedAttachmentWorkspaceShell', () => {
             expect(screen.queryByAltText('Homepage shot')).not.toBeInTheDocument();
         });
     });
+    it('loads images from the image tray and opens the selected image', async () => {
+        const user = userEvent.setup();
+        fetchTaskforceApi
+            .mockResolvedValueOnce({
+            ok: true,
+            json: async () => ({
+                images: [
+                    {
+                        assetId: 'asset-image-24',
+                        imageReferenceLabel: 'I-24',
+                        path: '/api/taskforce/context/workspaces%2Fworkspace-1%2Fassets%2Fimages%2Fasset-image-24.png',
+                        displayName: 'Reference image',
+                        originalFilename: 'reference.png',
+                        sizeBytes: 2048,
+                        updatedAt: '2026-03-25T12:00:00.000Z',
+                        attachmentCount: 0,
+                        sessionCount: 0,
+                    },
+                ],
+            }),
+        })
+            .mockResolvedValueOnce({
+            ok: true,
+            json: async () => ({ sessions: [] }),
+        })
+            .mockResolvedValueOnce({
+            ok: true,
+            json: async () => ({
+                session: buildSessionResponse({
+                    id: 'session-ref-1',
+                    taskId: '',
+                    baseImageAssetId: 'asset-image-24',
+                    title: 'Reference image review',
+                }),
+            }),
+        });
+        function ControlledImageTrayHarness() {
+            const [target, setTarget] = React.useState(null);
+            const [sessionId, setSessionId] = React.useState(null);
+            return (_jsx(AnnotatedAttachmentWorkspaceShell, { workspaceId: "workspace-1", imageTrayOpen: true, requestedTarget: target, requestedSessionId: sessionId, onOpenTarget: (nextTarget, options) => {
+                    setTarget(nextTarget);
+                    setSessionId(options?.sessionId ?? null);
+                } }));
+        }
+        render(_jsx(ControlledImageTrayHarness, {}));
+        expect(await screen.findByRole('button', { name: /reference image/i })).toBeInTheDocument();
+        await user.click(screen.getByRole('button', { name: /reference image/i }));
+        await waitFor(() => expect(fetchTaskforceApi).toHaveBeenNthCalledWith(1, '/api/taskforce/annotated-attachments/images?workspaceId=workspace-1', expect.objectContaining({ cache: 'no-store' }), ''));
+        await waitFor(() => expect(fetchTaskforceApi).toHaveBeenNthCalledWith(2, '/api/taskforce/annotated-attachments/sessions?workspaceId=workspace-1&imageAssetId=asset-image-24', expect.any(Object), ''));
+        expect(await screen.findByAltText('Reference image')).toBeInTheDocument();
+        expect(await findSessionCard('Reference image review')).toBeInTheDocument();
+    });
     it('does not revert to the previous image while opening a pasted image in controlled mode', async () => {
         const user = userEvent.setup();
         const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue({

package/dist/components/features/DocumentIndex.d.ts

@@ -11,8 +11,8 @@ interface Props {
     }>;
     onSearchChange: (q: string) => void;
     onSelect: (doc: DocMeta) => void;
-    onRefresh: () => void;
+    onCloseTray?: () => void;
     hasActiveFilters: boolean;
 }
-export declare function DocumentIndex({ documents, selectedDocId, loading, error, searchQuery, taskById, onSearchChange, onSelect, onRefresh, hasActiveFilters, }: Props): import("react/jsx-runtime").JSX.Element;
+export declare function DocumentIndex({ documents, selectedDocId, loading, error, searchQuery, taskById, onSearchChange, onSelect, onCloseTray, hasActiveFilters, }: Props): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/features/DocumentIndex.js

@@ -1,6 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { Search, RefreshCw, FileText, ClipboardList, Eye, BookOpen, File } from 'lucide-react';
-import styles from '../../Taskforce.module.css';
+import { Search, FileText, ClipboardList, Eye, BookOpen, File, ChevronLeft } from 'lucide-react';
 import indexStyles from './DocumentIndex.module.css';
 import { getEffectiveAttachmentState } from './documentWorkspaceModel';
 import { getReadableDocumentName } from '../../utils/documentNames';
@@ -42,8 +41,8 @@ function handleItemKeyDown(event, onSelect) {
     event.preventDefault();
     onSelect();
 }
-export function DocumentIndex({ documents, selectedDocId, loading, error, searchQuery, taskById, onSearchChange, onSelect, onRefresh, hasActiveFilters, }) {
-    return (_jsxs("div", { className: indexStyles.index, children: [_jsxs("div", { className: indexStyles.header, children: [_jsxs("span", { className: indexStyles.title, children: [_jsx(FileText, { size: 14 }), "Documents"] }), _jsx("button", { className: indexStyles.refreshBtn, onClick: onRefresh, title: "Refresh document list", disabled: loading, children: _jsx(RefreshCw, { size: 13, className: loading ? styles.docSpinning : undefined }) })] }), _jsxs("div", { className: indexStyles.search, children: [_jsx(Search, { size: 12, className: indexStyles.searchIcon }), _jsx("input", { type: "text", placeholder: "Search documents\u2026", value: searchQuery, onChange: e => onSearchChange(e.target.value), className: indexStyles.searchInput })] }), _jsxs("div", { className: `${indexStyles.list} tf-scrollbar`, children: [loading && (_jsx("div", { className: indexStyles.state, children: "Loading documents\u2026" })), !loading && error && (_jsx("div", { className: indexStyles.stateError, children: error })), !loading && !error && documents.length === 0 && (_jsx("div", { className: indexStyles.state, children: hasActiveFilters
+export function DocumentIndex({ documents, selectedDocId, loading, error, searchQuery, taskById, onSearchChange, onSelect, onCloseTray, hasActiveFilters, }) {
+    return (_jsxs("div", { className: indexStyles.index, children: [_jsxs("div", { className: indexStyles.header, children: [_jsxs("span", { className: indexStyles.title, children: [_jsx(FileText, { size: 14 }), "Documents"] }), onCloseTray ? (_jsx("button", { type: "button", className: "tf-control-icon", onClick: onCloseTray, title: "Collapse document tray", "aria-label": "Collapse document tray", children: _jsx(ChevronLeft, { size: 16 }) })) : null] }), _jsxs("div", { className: indexStyles.search, children: [_jsx(Search, { size: 12, className: indexStyles.searchIcon }), _jsx("input", { type: "text", placeholder: "Search documents\u2026", value: searchQuery, onChange: e => onSearchChange(e.target.value), className: indexStyles.searchInput })] }), _jsxs("div", { className: `${indexStyles.list} tf-scrollbar`, children: [loading && (_jsx("div", { className: indexStyles.state, children: "Loading documents\u2026" })), !loading && error && (_jsx("div", { className: indexStyles.stateError, children: error })), !loading && !error && documents.length === 0 && (_jsx("div", { className: indexStyles.state, children: hasActiveFilters
                             ? 'No documents match your filters.'
                             : 'No documents found. Documents added as task attachments will appear here.' })), !loading && documents.map(doc => {
                         const task = doc.taskId ? taskById.get(doc.taskId) : null;

package/dist/components/features/DocumentViewer.d.ts

@@ -7,11 +7,13 @@ interface Props {
     tasks?: Array<{
         id: string;
         title: string;
+        referenceLabel?: string | null;
     }>;
     apiBaseUrl?: string;
     onSaved?: (updatedAt: string) => void;
     onDeleted?: () => void;
+    onBackToTask?: (taskId: string) => void;
     enableTaskGeneration?: boolean;
 }
-export declare function DocumentViewer({ doc, taskTitle, tasks, apiBaseUrl, onSaved, onDeleted, enableTaskGeneration }: Props): import("react/jsx-runtime").JSX.Element;
+export declare function DocumentViewer({ doc, taskTitle, tasks, apiBaseUrl, onSaved, onDeleted, onBackToTask, enableTaskGeneration }: Props): import("react/jsx-runtime").JSX.Element;
 export {};