@taskforcehq/taskforce 0.3.306 → 0.3.307

package/dist/hooks/useTaskforce.runtime-routing.test.js

@@ -149,4 +149,98 @@ describe('useTaskforce runtime API routing', () => {
         ]));
         expect(taskforceReads.some((url) => url.startsWith('https://performance-app.taskforcehq.ai'))).toBe(false);
     });
+    it('does not stall cloud bootstrap when optional build metadata times out', async () => {
+        vi.stubGlobal('fetch', vi.fn((input) => {
+            const url = requestUrl(input);
+            if (url.includes('/api/taskforce/auth/runtime-config')) {
+                return jsonResponse({
+                    config: {
+                        runtimeMode: 'cloud',
+                        workspaceMode: 'multi-cloud',
+                        authSource: 'cloud',
+                        workspaceSwitchingEnabled: true
+                    }
+                });
+            }
+            if (url.includes('/api/taskforce/auth/session')) {
+                return jsonResponse({
+                    authenticated: true,
+                    authRequiredForApi: true,
+                    betaAccess: true,
+                    userId: 'user-1',
+                    email: 'user@example.com',
+                    workspaceId: 'workspace-cloud-1'
+                });
+            }
+            if (url.includes('/api/taskforce/workspaces')) {
+                return jsonResponse({
+                    success: true,
+                    currentWorkspaceId: 'workspace-cloud-1',
+                    workspaces: [{ id: 'workspace-cloud-1', name: 'Cloud Workspace', role: 'owner' }]
+                });
+            }
+            if (url.includes('/api/taskforce/ui-state?key=app'))
+                return jsonResponse({ success: true, state: {} });
+            if (url.includes('/api/taskforce/ui-state?key=workspace-sync')) {
+                return jsonResponse({ success: true, state: { version: 2, enabled: false, phase: 'idle', pullCursor: null } });
+            }
+            if (url.includes('/api/taskforce/config')) {
+                return jsonResponse({
+                    projectName: 'Cloud Project',
+                    workspaceId: 'workspace-cloud-1',
+                    runtimeMode: 'cloud',
+                    authRequiredForApi: true,
+                    userId: 'user-1',
+                    setupState: {
+                        globalSetupState: 'complete',
+                        workspaceSetupState: 'complete',
+                        workspaceId: 'workspace-cloud-1'
+                    }
+                });
+            }
+            if (url.includes('/api/taskforce/version')) {
+                return Promise.reject(new DOMException('The operation was aborted.', 'AbortError'));
+            }
+            if (url.includes('/api/taskforce/taxonomy-state')) {
+                return jsonResponse({
+                    categories: [{ value: 'general', label: 'General' }],
+                    types: [{ value: 'feature', label: 'Feature' }],
+                    priorities: [{ value: 2, label: 'Medium' }],
+                    taxonomies: []
+                });
+            }
+            if (url.includes('/api/taskforce/workflow-templates'))
+                return jsonResponse({ workflows: [] });
+            if (url.includes('/api/taskforce/initiative-templates'))
+                return jsonResponse({ templates: [] });
+            if (url.includes('/api/taskforce/environments'))
+                return jsonResponse({ environments: [] });
+            if (url.includes('/api/taskforce/workspace/assignee-options'))
+                return jsonResponse({ assignees: [] });
+            if (url.includes('/api/taskforce/auth/workspace-members'))
+                return jsonResponse({ users: [] });
+            if (url.includes('/api/taskforce/planning/bootstrap'))
+                return jsonResponse({ initiatives: [], workstreams: [], workstreamTaskSummaries: [] });
+            if (url.includes('/api/taskforce/tasks'))
+                return jsonResponse({ tasks: [] });
+            if (url.includes('/api/taskforce/archive'))
+                return jsonResponse({ archived: [] });
+            if (url.includes('/api/taskforce/data-version'))
+                return jsonResponse({ dataVersion: 1 });
+            if (url.includes('/api/taskforce/global-settings'))
+                return jsonResponse({});
+            return jsonResponse({});
+        }));
+        const { result } = renderHook(() => useTaskforce({
+            config: {
+                cloudAuthBaseUrl: 'https://performance-app.taskforcehq.ai'
+            }
+        }), { wrapper });
+        await waitFor(() => {
+            expect(result.current.runtimeMode).toBe('cloud');
+            expect(result.current.bootstrapState.ready).toBe(true);
+            expect(result.current.bootstrapState.stalled).toBe(false);
+            expect(result.current.bootstrapState.error).toBeNull();
+        }, { timeout: 2500 });
+    });
 });

package/dist/hooks/useTaskforce.sync-behavior.test.js

@@ -487,6 +487,105 @@ describe('useTaskforce sync behavior', () => {
             expect(result.current.workstreams.some((item) => item.id === workstream.id)).toBe(true);
         }, { timeout: 7000 });
     }, 10000);
+    it('retries a timed-out planning bootstrap without falling back to legacy endpoints during startup', async () => {
+        const initiative = {
+            id: 'initiative-timeout-1',
+            title: 'Timeout initiative',
+            description: null,
+            createdAt: '2026-03-15T10:00:00.000Z',
+        };
+        const workstream = {
+            id: 'workstream-timeout-1',
+            title: 'Timeout workstream',
+            description: null,
+            initiativeId: initiative.id,
+            createdAt: '2026-03-15T10:05:00.000Z',
+        };
+        let planningBootstrapCalls = 0;
+        let initiativesCalls = 0;
+        let workstreamsCalls = 0;
+        vi.stubGlobal('fetch', vi.fn((url) => {
+            if (url.includes('/api/taskforce/auth/runtime-config')) {
+                return jsonResponse({ config: { runtimeMode: 'local', workspaceMode: 'single-local', authSource: 'cloud' } });
+            }
+            if (url.includes('/api/taskforce/auth/session')) {
+                return jsonResponse({
+                    authenticated: false,
+                    authRequiredForApi: false,
+                    betaAccess: true,
+                    userId: 'anonymous',
+                    email: '',
+                    workspaceId: 'workspace-local-active'
+                });
+            }
+            if (url.includes('/api/taskforce/ui-state?key=app'))
+                return jsonResponse({ success: true, state: {} });
+            if (url.includes('/api/taskforce/ui-state?key=workspace-sync')) {
+                return jsonResponse({ success: true, state: { version: 2, enabled: false, phase: 'idle', pullCursor: null } });
+            }
+            if (url.includes('/api/taskforce/config')) {
+                return jsonResponse({
+                    projectName: 'Test Project',
+                    workspaceId: 'workspace-local-active',
+                    runtimeMode: 'local',
+                    setupState: {
+                        globalSetupState: 'complete',
+                        workspaceSetupState: 'complete',
+                        workspaceId: 'workspace-local-active'
+                    }
+                });
+            }
+            if (url.includes('/api/taskforce/global-settings'))
+                return jsonResponse({});
+            if (url.includes('/api/taskforce/categories'))
+                return jsonResponse({ categories: [{ value: 'general', label: 'General' }] });
+            if (url.includes('/api/taskforce/types'))
+                return jsonResponse({ types: [] });
+            if (url.includes('/api/taskforce/priorities'))
+                return jsonResponse({ priorities: [] });
+            if (url.includes('/api/taskforce/approaches'))
+                return jsonResponse({ approaches: [] });
+            if (url.includes('/api/taskforce/specialists'))
+                return jsonResponse({ specialists: [] });
+            if (url.includes('/api/taskforce/tasks'))
+                return jsonResponse({ tasks: [activeTask] });
+            if (url.includes('/api/taskforce/archive'))
+                return jsonResponse({ archived: [] });
+            if (url.includes('/api/taskforce/planning/bootstrap')) {
+                planningBootstrapCalls += 1;
+                if (planningBootstrapCalls === 1) {
+                    return Promise.reject(new DOMException('timed out', 'AbortError'));
+                }
+                return jsonResponse({
+                    initiatives: [initiative],
+                    workstreams: [workstream],
+                    workstreamTaskSummaries: [],
+                });
+            }
+            if (url.includes('/api/taskforce/initiatives')) {
+                initiativesCalls += 1;
+                return jsonResponse([initiative]);
+            }
+            if (url.includes('/api/taskforce/workstreams')) {
+                workstreamsCalls += 1;
+                return jsonResponse([workstream]);
+            }
+            if (url.includes('/api/taskforce/data-version'))
+                return jsonResponse({ dataVersion: 1 });
+            return jsonResponse({});
+        }));
+        const { result } = renderHook(() => useTaskforce({ config: {} }), { wrapper });
+        await waitFor(() => {
+            expect(result.current.tasks.some((task) => task.id === activeTask.id)).toBe(true);
+        });
+        await waitFor(() => {
+            expect(result.current.initiatives.some((item) => item.id === initiative.id)).toBe(true);
+            expect(result.current.workstreams.some((item) => item.id === workstream.id)).toBe(true);
+        }, { timeout: 7000 });
+        expect(planningBootstrapCalls).toBeGreaterThanOrEqual(2);
+        expect(initiativesCalls).toBe(0);
+        expect(workstreamsCalls).toBe(0);
+    }, 10000);
     it('does not block cloud bootstrap readiness on a slow planning bootstrap response', async () => {
         const delayedPlanningResponseMs = 1500;
         vi.stubGlobal('fetch', vi.fn((url) => {

package/dist/hooks/useWorkspaceSyncController.js

@@ -74,6 +74,12 @@ function buildWorkspaceSyncStatePatch(current, patch) {
     }
     return next;
 }
+function buildRemoteWorkspaceSyncStatePatch(state) {
+    return {
+        ...state,
+        pushBaseline: null
+    };
+}
 export function useWorkspaceSyncController(input) {
     const { currentWorkspaceId, setWorkspaceCloudSyncEnabled, setWorkspaceSyncPhase, setWorkspaceSyncSetupIntent, setWorkspaceLastPullAt, setWorkspaceLastPushAt, setWorkspaceLastErrorMessage } = input;
     const [workspaceRetryAt, setWorkspaceRetryAt] = useState(null);
@@ -297,7 +303,7 @@ export function useWorkspaceSyncController(input) {
         const result = await persistRemoteUiState({
             workspaceId: currentWorkspaceId,
             stateKey: 'workspace-sync',
-            patch: next,
+            patch: buildRemoteWorkspaceSyncStatePatch(next),
             throwOnError: true,
             respectFailureCooldown: false
         });

package/dist/hooks/useWorkspaceSyncController.test.js

@@ -89,6 +89,54 @@ describe('useWorkspaceSyncController', () => {
         expect(input.setWorkspaceCloudSyncEnabled).toHaveBeenCalledWith(true);
         expect(input.setWorkspaceSyncPhase).toHaveBeenCalledWith('attach-cloud');
     });
+    it('clears local-only push baselines from remote ui-state patches', async () => {
+        const uiStatePosts = [];
+        vi.stubGlobal('fetch', vi.fn((url, init) => {
+            if (url.includes('/api/taskforce/ui-state?key=workspace-sync')) {
+                return Promise.resolve({
+                    ok: true,
+                    json: () => Promise.resolve({
+                        success: true,
+                        state: {
+                            version: 2,
+                            enabled: true,
+                            phase: 'active',
+                            pullCursor: 'cursor-1',
+                            pushBaseline: {
+                                taskIds: ['task-1'],
+                                taskWatermarks: [['task-1', 'x'.repeat(1024 * 1024)]],
+                                initiativeWatermarks: [],
+                                workstreamWatermarks: [],
+                                aiProfileWatermarks: [],
+                                documentWatermarks: [],
+                                assetWatermarks: [],
+                                documentReviewSessionWatermarks: [],
+                                documentReviewCommentWatermarks: [],
+                                annotatedAttachmentSessionWatermarks: [],
+                                taskEventWatermarks: [],
+                                taxonomyStateFingerprint: ''
+                            }
+                        }
+                    })
+                });
+            }
+            if (url.includes('/api/taskforce/ui-state') && String(init?.method || '').toUpperCase() === 'POST') {
+                uiStatePosts.push(JSON.parse(String(init?.body || '{}')));
+                return Promise.resolve({ ok: true, json: () => Promise.resolve({ success: true }) });
+            }
+            return Promise.resolve({ ok: true, json: () => Promise.resolve({ success: true }) });
+        }));
+        const { result } = renderHook(() => useWorkspaceSyncController(makeInput()));
+        await act(async () => {
+            await result.current.loadWorkspaceSyncState();
+            await result.current.persistWorkspaceSyncPatch({ lastPullAt: '2026-04-27T20:30:00.000Z' });
+        });
+        expect(result.current.readWorkspaceSyncStateSnapshot().pushBaseline?.taskWatermarks[0]?.[1]).toHaveLength(1024 * 1024);
+        expect(uiStatePosts).toHaveLength(1);
+        expect(uiStatePosts[0]?.patch?.lastPullAt).toBe('2026-04-27T20:30:00.000Z');
+        expect(uiStatePosts[0]?.patch?.pushBaseline).toBeNull();
+        expect(JSON.stringify(uiStatePosts[0])).not.toContain('xxxx');
+    });
     it('persists attach-cloud phase when enabling sync for an existing cloud workspace', async () => {
         const uiStatePosts = [];
         vi.stubGlobal('fetch', vi.fn((url, init) => {

package/dist/hooks/workspace/useTaskforceWorkspaceBootstrap.js

@@ -2,6 +2,7 @@ import { useCallback, useEffect } from 'react';
 import { createDefaultAssigneeOptions, createWorkspaceAssigneeOptions, mergeAssigneeOptions } from '../../utils/assignees';
 import { hasWorkspaceTaxonomyStatePayload, normalizeWorkspaceTaxonomyStatePayload } from '../../shared/taxonomyState.js';
 import { logBootstrapDebug, readPersistedWorkspaceId } from './workspaceLocalState';
+import { resolveBootstrapRequestTimeoutMs } from '../bootstrapTimeouts';
 function getBootstrapTimestamp() {
     return typeof performance !== 'undefined' ? performance.now() : Date.now();
 }
@@ -135,7 +136,7 @@ export function useTaskforceWorkspaceBootstrap(args) {
         const abortController = new AbortController();
         bootstrapConfigAbortRef.current = abortController;
         try {
-            const res = await fetchWithTimeout('/api/taskforce/config', undefined, 12000, { signal: abortController.signal });
+            const res = await fetchWithTimeout('/api/taskforce/config', undefined, resolveBootstrapRequestTimeoutMs(runtimeMode), { signal: abortController.signal });
             if (isWorkspaceEpochStale(requestState))
                 return;
             if (res.status === 401) {
@@ -193,7 +194,7 @@ export function useTaskforceWorkspaceBootstrap(args) {
             if (bootstrapConfigAbortRef.current === abortController)
                 bootstrapConfigAbortRef.current = null;
         }
-    }, [applyBootstrapConfig, bootstrapConfigAbortRef, currentWorkspaceIdRef, fetchBuildInfo, fetchWithTimeout, getWorkspaceRequestState, handleUnauthorized, hasLoadedUiStateRef, isAbortError, isBootstrapTimeoutError, isWorkspaceEpochStale, loadPersistedUiState, markBootstrapPhase, markBootstrapStalled, setConfigLoaded, shouldBlockProtectedApiCalls, shouldDeferProtectedApiCalls]);
+    }, [applyBootstrapConfig, bootstrapConfigAbortRef, currentWorkspaceIdRef, fetchBuildInfo, fetchWithTimeout, getWorkspaceRequestState, handleUnauthorized, hasLoadedUiStateRef, isAbortError, isBootstrapTimeoutError, isWorkspaceEpochStale, loadPersistedUiState, markBootstrapPhase, markBootstrapStalled, runtimeMode, setConfigLoaded, shouldBlockProtectedApiCalls, shouldDeferProtectedApiCalls]);
     const fetchConfig = useCallback(async (options) => {
         await fetchBootstrapConfig(options);
         await fetchReferenceData(options);
@@ -219,7 +220,7 @@ export function useTaskforceWorkspaceBootstrap(args) {
         const abortController = new AbortController();
         workspaceListAbortRef.current = abortController;
         try {
-            const res = await fetchWithTimeout('/api/taskforce/workspaces', { method: 'GET', credentials: 'include' }, 12000, { signal: abortController.signal });
+            const res = await fetchWithTimeout('/api/taskforce/workspaces', { method: 'GET', credentials: 'include' }, resolveBootstrapRequestTimeoutMs(runtimeMode), { signal: abortController.signal });
             if (isWorkspaceEpochStale(requestState))
                 return { success: false, error: 'Workspace changed while loading workspaces.' };
             if (res.status === 401) {
@@ -284,9 +285,9 @@ export function useTaskforceWorkspaceBootstrap(args) {
         setAssigneeOptionsLoaded(false);
         try {
             const [assigneeResult, workspaceMembersResult] = await Promise.all([
-                fetchWithTimeout('/api/taskforce/workspace/assignee-options', { method: 'GET', credentials: 'include' }, 12000, { signal: abortController.signal }),
+                fetchWithTimeout('/api/taskforce/workspace/assignee-options', { method: 'GET', credentials: 'include' }, resolveBootstrapRequestTimeoutMs(runtimeMode), { signal: abortController.signal }),
                 (authSessionResolved && isAuthenticated)
-                    ? fetchWithTimeout('/api/taskforce/auth/workspace-members', { method: 'GET', credentials: 'include' }, 12000, { signal: abortController.signal }).catch(() => null)
+                    ? fetchWithTimeout('/api/taskforce/auth/workspace-members', { method: 'GET', credentials: 'include' }, resolveBootstrapRequestTimeoutMs(runtimeMode), { signal: abortController.signal }).catch(() => null)
                     : Promise.resolve(null)
             ]);
             if (isWorkspaceRequestStale(requestState))
@@ -330,7 +331,13 @@ export function useTaskforceWorkspaceBootstrap(args) {
                         icon: String(entry?.icon || 'Bot'),
                         color: String(entry?.color || '#8b5cf6'),
                         kind: 'agent',
-                        avatarUrl: typeof entry?.avatarUrl === 'string' && entry.avatarUrl.trim().length > 0 ? entry.avatarUrl.trim() : null
+                        avatarUrl: typeof entry?.avatarUrl === 'string' && entry.avatarUrl.trim().length > 0 ? entry.avatarUrl.trim() : null,
+                        avatarRevision: Number.isFinite(Number(entry?.avatarRevision)) ? Math.max(0, Math.floor(Number(entry.avatarRevision))) : null,
+                        avatarUpdatedAt: typeof entry?.avatarUpdatedAt === 'string' && entry.avatarUpdatedAt.trim().length > 0 ? entry.avatarUpdatedAt.trim() : null,
+                        username: typeof entry?.username === 'string' && entry.username.trim().length > 0 ? entry.username.trim() : null,
+                        archivedAt: typeof entry?.archivedAt === 'string' && entry.archivedAt.trim().length > 0 ? entry.archivedAt.trim() : null,
+                        createdAt: typeof entry?.createdAt === 'string' && entry.createdAt.trim().length > 0 ? entry.createdAt.trim() : null,
+                        updatedAt: typeof entry?.updatedAt === 'string' && entry.updatedAt.trim().length > 0 ? entry.updatedAt.trim() : null
                     };
                 if (kindRaw === 'member' || kindRaw === 'human')
                     return {
@@ -400,7 +407,7 @@ export function useTaskforceWorkspaceBootstrap(args) {
             if (assigneeOptionsAbortRef.current === abortController)
                 assigneeOptionsAbortRef.current = null;
         }
-    }, [assigneeOptionsAbortRef, authSessionResolved, authUserAvatarUrl, authUserId, fetchWithTimeout, getWorkspaceRequestState, isAbortError, isAuthenticated, isWorkspaceRequestStale, setAssigneeOptions, setAssigneeOptionsLoaded, setHydratedWorkspaceRole, workspaceSwitchingEnabled]);
+    }, [assigneeOptionsAbortRef, authSessionResolved, authUserAvatarUrl, authUserId, fetchWithTimeout, getWorkspaceRequestState, isAbortError, isAuthenticated, isWorkspaceRequestStale, runtimeMode, setAssigneeOptions, setAssigneeOptionsLoaded, setHydratedWorkspaceRole, workspaceSwitchingEnabled]);
     const switchWorkspace = useCallback(async (workspaceId, options) => {
         if (!workspaceSwitchingEnabled)
             return { success: false, error: 'Workspace switching is unavailable in local mode.', code: 'WORKSPACE_SWITCHING_DISABLED' };

package/dist/mcp/canonicalAssetHelpers.d.ts

@@ -1,4 +1,4 @@
-import type { WorkspaceAssetEntry, WorkspaceAssetKind, WorkspaceAssetLinkRole, WorkspaceAssetScanStatus, WorkspaceAssetStore } from '../storage/workspaceAssetStore.js';
+import type { WorkspaceAssetEntry, WorkspaceAssetKind, WorkspaceAssetLinkRole, WorkspaceAssetLinkTargetType, WorkspaceAssetScanStatus, WorkspaceAssetStore } from '../storage/workspaceAssetStore.js';
 import type { McpTaskAttachmentDescriptor, TaskAttachmentRecord } from './taskAttachmentTypes.js';
 export interface CanonicalAssetHelpersDeps {
     activeWorkspaceId: string;
@@ -9,6 +9,7 @@ export interface CanonicalAssetHelpersDeps {
         getObject(storageKey: string): Promise<{
             body: Buffer;
         } | null>;
+        putObject?(storageKey: string, body: Buffer, contentType: string): Promise<void>;
     } | null;
     sanitizeFilenameForPath: (filenameRaw: unknown, fallback?: string) => string;
     sanitizeDisplayName: (valueRaw: unknown, fallback: string) => string;
@@ -31,7 +32,7 @@ export declare function createCanonicalAssetHelpers(deps: CanonicalAssetHelpersD
     getAttachmentAssetRecord: (attachment: TaskAttachmentRecord) => WorkspaceAssetEntry | null;
     buildAttachmentDownloadUrl: (attachment: McpTaskAttachmentDescriptor) => string;
     buildDocumentDownloadUrl: (asset: WorkspaceAssetEntry) => string;
-    readCanonicalAttachmentBuffer: (taskId: string, attachment: McpTaskAttachmentDescriptor) => Promise<Buffer>;
+    readCanonicalAttachmentBuffer: (taskId: string, attachment: McpTaskAttachmentDescriptor, targetLabel?: string) => Promise<Buffer>;
     readCanonicalDocumentBuffer: (asset: WorkspaceAssetEntry) => Promise<Buffer>;
     toTaskAttachmentRecord: (attachment: string | TaskAttachmentRecord) => TaskAttachmentRecord;
     resolveAttachmentLogicalFilename: (attachmentInput: string | TaskAttachmentRecord, assetOverride?: ReturnType<(attachment: TaskAttachmentRecord) => WorkspaceAssetEntry | null> | null) => string;
@@ -47,7 +48,7 @@ export declare function createCanonicalAssetHelpers(deps: CanonicalAssetHelpersD
         absolutePath: string;
         logicalFilename: string;
     };
-    ensureCanonicalTaskAttachment: (relativePathRaw: string, taskIdRaw: string, captionRaw: string | undefined, timestampRaw: string | undefined, role: WorkspaceAssetLinkRole, options?: {
+    ensureCanonicalAttachment: (relativePathRaw: string, targetTypeRaw: WorkspaceAssetLinkTargetType, targetIdRaw: string, captionRaw: string | undefined, timestampRaw: string | undefined, role: WorkspaceAssetLinkRole, options?: {
         originalFilename?: string;
         logicalName?: string;
         assetId?: string;
@@ -57,7 +58,18 @@ export declare function createCanonicalAssetHelpers(deps: CanonicalAssetHelpersD
         scanStatus?: WorkspaceAssetScanStatus;
         scanEngine?: string | null;
         scanDetails?: string | null;
-    }) => WorkspaceAssetEntry | null;
+    }) => Promise<WorkspaceAssetEntry | null>;
+    ensureCanonicalTaskAttachment: (relativePathRaw: string, taskIdRaw: string, captionRaw: string | undefined, timestampRaw: string | undefined, role: WorkspaceAssetLinkRole, options?: Parameters<(relativePathRaw: string, targetTypeRaw: WorkspaceAssetLinkTargetType, targetIdRaw: string, captionRaw: string | undefined, timestampRaw: string | undefined, role: WorkspaceAssetLinkRole, options?: {
+        originalFilename?: string;
+        logicalName?: string;
+        assetId?: string;
+        documentId?: string | null;
+        createdAt?: string;
+        createdByUserId?: string | null;
+        scanStatus?: WorkspaceAssetScanStatus;
+        scanEngine?: string | null;
+        scanDetails?: string | null;
+    }) => Promise<WorkspaceAssetEntry | null>>[6]) => Promise<WorkspaceAssetEntry | null>;
     buildCanonicalWorkspaceAssetRelativePath: (params: {
         workspaceIdRaw: unknown;
         kind: WorkspaceAssetKind;

package/dist/mcp/canonicalAssetHelpers.js

@@ -65,13 +65,13 @@ export function createCanonicalAssetHelpers(deps) {
         ];
         return parts.join(', ');
     };
-    const readCanonicalAttachmentBuffer = async (taskId, attachment) => {
+    const readCanonicalAttachmentBuffer = async (taskId, attachment, targetLabel = 'task') => {
         const assetId = String(attachment.assetId || '').trim();
         const asset = assetId && deps.workspaceAssetStore
             ? deps.workspaceAssetStore.get(assetId, deps.activeWorkspaceId)
             : null;
         if (!asset || asset.deletedAt) {
-            throw new Error(`Attachment ${attachment.attachmentId} not found on task ${taskId}`);
+            throw new Error(`Attachment ${attachment.attachmentId} not found on ${targetLabel} ${taskId}`);
         }
         if (asset.scanStatus === 'infected') {
             throw new Error('Attachment is quarantined');
@@ -93,16 +93,16 @@ export function createCanonicalAssetHelpers(deps) {
                 throw new Error(`Attachment read failed from R2 (${attachmentContext}): ${message || 'Unknown object storage error'}`);
             }
             if (!object) {
-                throw new Error(`Attachment ${attachment.attachmentId} not found on task ${taskId}`);
+                throw new Error(`Attachment ${attachment.attachmentId} not found on ${targetLabel} ${taskId}`);
             }
             return object.body;
         }
         const resolvedPath = path.resolve(deps.basePath, asset.storageKey);
         if (!resolvedPath.startsWith(path.resolve(deps.basePath))) {
-            throw new Error(`Attachment ${attachment.attachmentId} not found on task ${taskId}`);
+            throw new Error(`Attachment ${attachment.attachmentId} not found on ${targetLabel} ${taskId}`);
         }
         if (!fs.existsSync(resolvedPath) || !fs.statSync(resolvedPath).isFile()) {
-            throw new Error(`Attachment ${attachment.attachmentId} not found on task ${taskId}`);
+            throw new Error(`Attachment ${attachment.attachmentId} not found on ${targetLabel} ${taskId}`);
         }
         return fs.readFileSync(resolvedPath);
     };
@@ -189,12 +189,13 @@ export function createCanonicalAssetHelpers(deps) {
         }
         return null;
     };
-    const ensureCanonicalTaskAttachment = (relativePathRaw, taskIdRaw, captionRaw, timestampRaw, role, options) => {
+    const ensureCanonicalAttachment = async (relativePathRaw, targetTypeRaw, targetIdRaw, captionRaw, timestampRaw, role, options) => {
         if (!deps.workspaceAssetStore)
             return null;
         const relativePath = String(relativePathRaw || '').trim();
-        const taskId = String(taskIdRaw || '').trim();
-        if (!relativePath || !taskId)
+        const targetType = String(targetTypeRaw || 'task').trim();
+        const targetId = String(targetIdRaw || '').trim();
+        if (!relativePath || !targetId)
             return null;
         const absolutePath = path.resolve(deps.projectRoot, relativePath);
         if (!fs.existsSync(absolutePath) || !fs.statSync(absolutePath).isFile())
@@ -206,6 +207,10 @@ export function createCanonicalAssetHelpers(deps) {
         const kind = deps.inferAssetKind(relativePath, mimeType);
         const timestamp = String(timestampRaw || new Date().toISOString()).trim() || new Date().toISOString();
         const existing = deps.workspaceAssetStore.getByStorageKey(storageKey, deps.activeWorkspaceId);
+        const shouldPersistToObjectStorage = typeof deps.objectStorageClient?.putObject === 'function';
+        if (shouldPersistToObjectStorage) {
+            await deps.objectStorageClient.putObject(storageKey, buffer, mimeType || 'application/octet-stream');
+        }
         const originalFilename = deps.sanitizeFilenameForPath(options?.originalFilename || existing?.originalFilename || path.basename(relativePath));
         const logicalName = deps.sanitizeDisplayName(options?.logicalName || existing?.logicalName || originalFilename, originalFilename);
         const asset = deps.workspaceAssetStore.upsertAsset({
@@ -215,7 +220,7 @@ export function createCanonicalAssetHelpers(deps) {
             logicalName,
             originalFilename,
             mimeType,
-            storageProvider: 'local',
+            storageProvider: shouldPersistToObjectStorage ? 'r2' : 'local',
             storageKey,
             contentSha256: createHash('sha256').update(buffer).digest('hex'),
             sizeBytes: stats.size,
@@ -234,7 +239,8 @@ export function createCanonicalAssetHelpers(deps) {
         deps.workspaceAssetStore.upsertLink({
             workspaceId: deps.activeWorkspaceId,
             assetId: asset.assetId,
-            taskId,
+            targetType,
+            targetId,
             role,
             displayName: kind === 'document' ? null : (captionRaw || null),
             updatedAt: timestamp,
@@ -242,6 +248,7 @@ export function createCanonicalAssetHelpers(deps) {
         });
         return asset;
     };
+    const ensureCanonicalTaskAttachment = (relativePathRaw, taskIdRaw, captionRaw, timestampRaw, role, options) => ensureCanonicalAttachment(relativePathRaw, 'task', taskIdRaw, captionRaw, timestampRaw, role, options);
     return {
         normalizeAttachmentStorageKey,
         buildSyntheticAttachmentId,
@@ -253,6 +260,7 @@ export function createCanonicalAssetHelpers(deps) {
         toTaskAttachmentRecord,
         resolveAttachmentLogicalFilename,
         resolveCanonicalOverwriteTarget,
+        ensureCanonicalAttachment,
         ensureCanonicalTaskAttachment,
         buildCanonicalWorkspaceAssetRelativePath: deps.buildCanonicalWorkspaceAssetRelativePath,
     };

package/dist/mcp/canonicalAssetHelpers.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/mcp/canonicalAssetHelpers.test.js

@@ -0,0 +1,67 @@
+import { describe, expect, it, vi } from 'vitest';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { TaskforceCore } from '../core/Taskforce';
+import { createCanonicalAssetHelpers } from './canonicalAssetHelpers';
+function makeCore() {
+    const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-mcp-canonical-assets-'));
+    const core = new TaskforceCore({
+        projectRoot,
+        storagePath: path.join(projectRoot, '.taskforce')
+    });
+    return {
+        projectRoot,
+        core,
+        cleanup: () => fs.rmSync(projectRoot, { recursive: true, force: true })
+    };
+}
+describe('MCP canonical asset helpers', () => {
+    it('uploads canonical attachments to object storage before recording durable cloud metadata', async () => {
+        const { projectRoot, core, cleanup } = makeCore();
+        try {
+            core.createWorkspace({ workspaceId: 'workspace-1', name: 'Workspace 1' });
+            const task = core.createTask({ title: 'Object-backed attachment' }, { workspaceId: 'workspace-1' });
+            const relativePath = '.taskforce/workspaces/workspace-1/assets/documents/asset-test-note.md';
+            const absolutePath = path.join(projectRoot, relativePath);
+            fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+            fs.writeFileSync(absolutePath, '# Stored in object storage\n', 'utf8');
+            const putObject = vi.fn(async () => { });
+            const helpers = createCanonicalAssetHelpers({
+                activeWorkspaceId: 'workspace-1',
+                projectRoot,
+                basePath: core.getPaths().basePath,
+                workspaceAssetStore: core.getWorkspaceAssetStore(),
+                objectStorageClient: {
+                    getObject: vi.fn(async () => null),
+                    putObject,
+                },
+                sanitizeFilenameForPath: (value, fallback = 'file.txt') => String(value || fallback).trim() || fallback,
+                sanitizeDisplayName: (value, fallback) => String(value || fallback).trim() || fallback,
+                toPosixPath: (value) => value.replace(/\\/g, '/'),
+                inferMimeTypeFromPath: (value) => value.endsWith('.md') ? 'text/markdown' : 'application/octet-stream',
+                inferAssetKind: (value, mimeType) => (value.endsWith('.md') || mimeType === 'text/markdown' ? 'document' : 'file'),
+                buildCanonicalWorkspaceAssetRelativePath: () => ({
+                    assetId: 'asset-test-note',
+                    relativePath: 'workspaces/workspace-1/assets/documents/asset-test-note.md'
+                })
+            });
+            const asset = await helpers.ensureCanonicalTaskAttachment(relativePath, task.id, 'note.md', '2026-04-27T01:00:00.000Z', 'attachment', { originalFilename: 'note.md', logicalName: 'note.md' });
+            expect(putObject).toHaveBeenCalledWith('workspaces/workspace-1/assets/documents/asset-test-note.md', Buffer.from('# Stored in object storage\n', 'utf8'), 'text/markdown');
+            expect(asset?.storageProvider).toBe('r2');
+            expect(core.getWorkspaceAssetStore().get(asset.assetId, 'workspace-1')?.storageProvider).toBe('r2');
+            expect(core.getWorkspaceAssetStore().listLinksForTask(task.id, 'workspace-1')).toEqual(expect.arrayContaining([
+                expect.objectContaining({
+                    assetId: asset?.assetId,
+                    targetType: 'task',
+                    role: 'attachment',
+                    deletedAt: null,
+                })
+            ]));
+        }
+        finally {
+            core.close();
+            cleanup();
+        }
+    });
+});

package/dist/mcp/clientIntegrations.d.ts

@@ -31,6 +31,7 @@ export interface CloudMcpClientIntegration {
     serverConfig?: unknown;
     renderedText?: string;
 }
+export declare function buildLocalAiProfileEnv(clientId: McpClientId): Record<string, string>;
 export declare const MCP_CLIENT_OPTIONS: McpClientOption[];
 export declare function sanitizeMcpId(value: string, fallback: string): string;
 export declare function buildCloudMcpServerId(workspaceName?: string | null, projectName?: string | null): string;

package/dist/mcp/clientIntegrations.js

@@ -1,4 +1,29 @@
 import { buildAiProfileBootstrapHeaders } from './aiProfileBootstrap.js';
+const LOCAL_AI_PROFILE_DEFAULTS = {
+    general: { name: 'Taskforce MCP Agent', icon: 'Bot', role: 'AI collaborator', provider: 'MCP client', model: 'Local MCP', surfaceType: 'agent' },
+    cursor: { name: 'Cursor', icon: 'Bot', role: 'IDE coding assistant', provider: 'Cursor', model: 'Cursor', surfaceType: 'ide' },
+    cline: { name: 'Cline', icon: 'Bot', role: 'IDE coding assistant', provider: 'Cline', model: 'Cline', surfaceType: 'ide' },
+    vscode: { name: 'VS Code Copilot', icon: 'Bot', role: 'IDE coding assistant', provider: 'Microsoft', model: 'Copilot', surfaceType: 'ide' },
+    windsurf: { name: 'Windsurf', icon: 'Bot', role: 'IDE coding assistant', provider: 'Windsurf', model: 'Windsurf', surfaceType: 'ide' },
+    antigravity: { name: 'Antigravity', icon: 'Bot', role: 'Coding agent', provider: 'Google', model: 'Antigravity', surfaceType: 'coding_tool' },
+    openclaw: { name: 'OpenClaw', icon: 'Bot', role: 'AI agent', provider: 'OpenClaw', model: 'OpenClaw', surfaceType: 'agent' },
+    codex: { name: 'Codex', icon: 'Bot', role: 'Coding agent', provider: 'OpenAI', model: 'Codex', surfaceType: 'cli' },
+    'claude-code': { name: 'Claude Code', icon: 'Bot', role: 'Coding agent', provider: 'Anthropic', model: 'Claude Code', surfaceType: 'cli' },
+    'gemini-cli': { name: 'Gemini CLI', icon: 'Bot', role: 'Coding agent', provider: 'Google', model: 'Gemini CLI', surfaceType: 'cli' },
+    'claude-desktop': { name: 'Claude Desktop', icon: 'Bot', role: 'Desktop AI collaborator', provider: 'Anthropic', model: 'Claude Desktop', surfaceType: 'chat_app' },
+    'chatgpt-desktop': { name: 'ChatGPT Desktop', icon: 'Bot', role: 'Desktop AI collaborator', provider: 'OpenAI', model: 'ChatGPT Desktop', surfaceType: 'chat_app' },
+};
+export function buildLocalAiProfileEnv(clientId) {
+    const defaults = LOCAL_AI_PROFILE_DEFAULTS[clientId] || LOCAL_AI_PROFILE_DEFAULTS.general;
+    return {
+        TASKFORCE_AI_NAME: defaults.name,
+        TASKFORCE_AI_ICON: defaults.icon,
+        TASKFORCE_AI_ROLE: defaults.role,
+        TASKFORCE_AI_PROVIDER: defaults.provider,
+        TASKFORCE_AI_MODEL: defaults.model,
+        TASKFORCE_AI_SURFACE_TYPE: defaults.surfaceType,
+    };
+}
 export const MCP_CLIENT_OPTIONS = [
     { id: 'general', label: 'General' },
     { id: 'antigravity', label: 'Antigravity' },