@taskforcehq/taskforce 0.3.303 → 0.3.304

package/dist/mcp/runtime.js

@@ -3,10 +3,14 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ListResourceTemplatesRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, SubscribeRequestSchema, UnsubscribeRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import * as fs from 'fs';
 import * as path from 'path';
-import { createHash, randomUUID } from 'node:crypto';
+import { randomUUID } from 'node:crypto';
+import * as os from 'node:os';
 import { TaskforceCore, TaskforceRuleError } from '../core/Taskforce.js'; // Note .js extension for ESM
 import { COMPLEXITY_OPTIONS, resolveNumberOption, resolveStringOption, STATUS_OPTIONS } from './optionResolution.js';
 import { buildResolveAiProfileInputFromBootstrap } from './aiProfileBootstrap.js';
+import { createCanonicalAssetHelpers } from './canonicalAssetHelpers.js';
+import { createDocumentHelpers } from './documentHelpers.js';
+import { createTaskAttachmentHelpers } from './taskAttachmentHelpers.js';
 import { validateStructuredDocForAttach } from './structuredDocValidation.js';
 import { validateStructuredCommentForAdd } from './structuredCommentValidation.js';
 import { resolveDatabaseConfigFromEnv } from '../storage/providerConfig.js';
@@ -282,300 +286,38 @@ export function createTaskforceMcpServer(options = {}) {
         ? new ObjectStorageClient(objectStorageConfig)
         : null;
     const { basePath } = core.getPaths();
-    const normalizeAttachmentStorageKey = (pathValue, fsPathValue) => {
-        const fsPathRaw = String(fsPathValue || '').trim().replace(/\\/g, '/');
-        if (fsPathRaw) {
-            return fsPathRaw.replace(/^\.taskforce\//, '').trim() || null;
-        }
-        const pathRaw = String(pathValue || '').trim();
-        if (!pathRaw)
-            return null;
-        if (/^https?:\/\//i.test(pathRaw))
-            return pathRaw;
-        if (pathRaw.startsWith('/api/taskforce/context/')) {
-            return decodeURIComponent(pathRaw.slice('/api/taskforce/context/'.length)).trim() || null;
-        }
-        return null;
-    };
-    const buildSyntheticAttachmentId = (taskId, attachment) => {
-        const stableSource = [
-            taskId,
-            String(attachment.path || '').trim(),
-            String(attachment.fsPath || '').trim(),
-            String(attachment.caption || '').trim(),
-        ].join('::');
-        return `attachment-${createHash('sha256').update(stableSource).digest('hex').slice(0, 24)}`;
-    };
-    const getAttachmentAssetRecord = (attachment) => {
-        if (!workspaceAssetStore)
-            return null;
-        const assetId = String(attachment.assetId || '').trim();
-        if (assetId) {
-            const byId = workspaceAssetStore.get(assetId, ACTIVE_WORKSPACE_ID);
-            if (byId && !byId.deletedAt)
-                return byId;
-        }
-        const storageKey = normalizeAttachmentStorageKey(attachment.path, attachment.fsPath);
-        if (!storageKey || /^https?:\/\//i.test(storageKey))
-            return null;
-        const byStorageKey = workspaceAssetStore.getByStorageKey(storageKey, ACTIVE_WORKSPACE_ID);
-        if (byStorageKey && !byStorageKey.deletedAt)
-            return byStorageKey;
-        return null;
-    };
-    const isCanonicalDocumentAssetRecord = (asset) => isValidCanonicalDocumentAsset(asset);
-    const toTaskAttachmentRecord = (attachment) => {
-        if (typeof attachment === 'string') {
-            return { path: attachment };
-        }
-        return attachment;
-    };
-    const describeTaskAttachment = (taskId, attachmentInput) => {
-        const attachment = toTaskAttachmentRecord(attachmentInput);
-        const asset = getAttachmentAssetRecord(attachment);
-        const storageKey = normalizeAttachmentStorageKey(attachment.path, attachment.fsPath);
-        const assetId = String(attachment.assetId || asset?.assetId || '').trim() || undefined;
-        const source = (asset?.storageProvider === 'external' || /^https?:\/\//i.test(String(attachment.path || '').trim()))
-            ? 'external'
-            : 'canonical';
-        const mimeType = String(asset?.mimeType
-            || (storageKey && !/^https?:\/\//i.test(storageKey) ? inferMimeTypeFromPath(storageKey) : '')
-            || inferMimeTypeFromPath(String(attachment.originalFilename || attachment.displayName || attachment.caption || attachment.path || ''))).trim() || 'application/octet-stream';
-        const kind = asset?.kind || inferAssetKind(storageKey || String(attachment.path || ''), mimeType);
-        const isCanonicalDocument = Boolean(asset && isCanonicalDocumentAssetRecord(asset)) || (!asset && kind === 'document');
-        const referenceNumber = typeof attachment.referenceNumber === 'number'
-            ? attachment.referenceNumber
-            : (typeof asset?.referenceNumber === 'number' ? asset.referenceNumber : null);
-        const referenceLabel = String(attachment.referenceLabel
-            || (kind === 'image' ? getImageReferenceLabel(asset) : '')
-            || (isCanonicalDocument ? getDocumentReferenceLabel(asset) : '')).trim() || null;
-        const readableAsText = source === 'canonical' && isTextReadableMimeType(mimeType);
-        const canonicalDocumentHint = isCanonicalDocument && source === 'canonical' && asset
-            ? buildCanonicalDocumentAttachmentHint(asset)
-            : null;
-        return {
-            attachmentId: assetId || buildSyntheticAttachmentId(taskId, attachment),
-            ...(assetId ? { assetId } : {}),
-            ...(referenceNumber ? { referenceNumber } : {}),
-            ...(referenceLabel ? { referenceLabel } : {}),
-            ...(canonicalDocumentHint?.documentId ? { documentId: canonicalDocumentHint.documentId } : {}),
-            path: String(attachment.path || '').trim(),
-            ...(storageKey && !/^https?:\/\//i.test(storageKey) ? { fsPath: storageKey } : (attachment.fsPath ? { fsPath: String(attachment.fsPath).trim() } : {})),
-            ...(attachment.caption ? { caption: String(attachment.caption).trim() } : {}),
-            ...(attachment.displayName ? { displayName: String(attachment.displayName).trim() } : {}),
-            ...(attachment.originalFilename ? { originalFilename: String(attachment.originalFilename).trim() } : {}),
-            kind: isCanonicalDocument ? 'document' : kind,
-            mimeType,
-            sizeBytes: asset ? Number(asset.sizeBytes || 0) : null,
-            ...(attachment.timestamp ? { timestamp: String(attachment.timestamp).trim() } : {}),
-            source,
-            readableAsText,
-            ...(canonicalDocumentHint ? {
-                preferredNextTool: canonicalDocumentHint.preferredNextTool,
-                preferredWorkflow: canonicalDocumentHint.preferredWorkflow,
-                suggestedArgs: canonicalDocumentHint.suggestedArgs,
-                guidance: canonicalDocumentHint.guidance,
-            } : {}),
-        };
-    };
-    const listTaskAttachmentDescriptors = (task) => {
-        if (!task || !Array.isArray(task.attachments))
-            return [];
-        return task.attachments.map((attachment) => describeTaskAttachment(task.id, attachment));
-    };
-    const buildAttachmentDownloadUrl = (attachment) => {
-        if (attachment.source === 'external')
-            return attachment.path;
-        const safeName = encodeURIComponent(String(attachment.caption || attachment.displayName || attachment.originalFilename || path.basename(attachment.fsPath || attachment.path) || 'download').trim());
-        const joiner = attachment.path.includes('?') ? '&' : '?';
-        return `${attachment.path}${joiner}download=1&filename=${safeName}`;
-    };
-    const describeAttachmentStorageContext = (attachment, storageKey) => {
-        const parts = [
-            `attachmentId=${attachment.attachmentId}`,
-            `assetId=${String(attachment.assetId || 'unknown')}`,
-            `storageKey=${storageKey || 'unknown'}`
-        ];
-        return parts.join(', ');
-    };
-    const readCanonicalAttachmentBuffer = async (taskId, attachment) => {
-        const assetId = String(attachment.assetId || '').trim();
-        const asset = assetId && workspaceAssetStore
-            ? workspaceAssetStore.get(assetId, ACTIVE_WORKSPACE_ID)
-            : null;
-        if (!asset || asset.deletedAt) {
-            throw new Error(`Attachment ${attachment.attachmentId} not found on task ${taskId}`);
-        }
-        if (asset.scanStatus === 'infected') {
-            throw new Error('Attachment is quarantined');
-        }
-        if (asset.scanStatus === 'pending') {
-            throw new Error('Attachment scan pending');
-        }
-        if (asset.storageProvider === 'r2') {
-            const attachmentContext = describeAttachmentStorageContext(attachment, asset.storageKey);
-            if (!objectStorageClient) {
-                throw new Error(`Attachment read failed from R2 because object storage is not configured in this MCP runtime (${attachmentContext})`);
-            }
-            let object;
-            try {
-                object = await objectStorageClient.getObject(asset.storageKey);
-            }
-            catch (error) {
-                const message = error instanceof Error ? String(error.message || '').trim() : String(error || '').trim();
-                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}`);
-            }
-            return object.body;
-        }
-        const resolvedPath = path.resolve(basePath, asset.storageKey);
-        if (!resolvedPath.startsWith(path.resolve(basePath))) {
-            throw new Error(`Attachment ${attachment.attachmentId} not found on task ${taskId}`);
-        }
-        if (!fs.existsSync(resolvedPath) || !fs.statSync(resolvedPath).isFile()) {
-            throw new Error(`Attachment ${attachment.attachmentId} not found on task ${taskId}`);
-        }
-        return fs.readFileSync(resolvedPath);
-    };
-    const readCanonicalDocumentBuffer = async (asset) => {
-        if (asset.deletedAt || asset.kind !== 'document') {
-            throw new Error(`Document ${asset.assetId} not found in workspace ${ACTIVE_WORKSPACE_ID}.`);
-        }
-        if (asset.scanStatus === 'infected') {
-            throw new Error('Document is quarantined');
-        }
-        if (asset.scanStatus === 'pending') {
-            throw new Error('Document scan pending');
-        }
-        if (asset.storageProvider === 'r2') {
-            if (!objectStorageClient) {
-                throw new Error(`Document read failed from R2 because object storage is not configured in this MCP runtime (assetId=${asset.assetId}, storageKey=${asset.storageKey || 'unknown'})`);
-            }
-            let object;
-            try {
-                object = await objectStorageClient.getObject(asset.storageKey);
-            }
-            catch (error) {
-                const message = error instanceof Error ? String(error.message || '').trim() : String(error || '').trim();
-                throw new Error(`Document read failed from R2 (assetId=${asset.assetId}, storageKey=${asset.storageKey || 'unknown'}): ${message || 'Unknown object storage error'}`);
-            }
-            if (!object) {
-                throw new Error(`Document ${asset.assetId} not found in workspace ${ACTIVE_WORKSPACE_ID}.`);
-            }
-            return object.body;
-        }
-        const resolvedPath = path.resolve(basePath, asset.storageKey);
-        if (!resolvedPath.startsWith(path.resolve(basePath))) {
-            throw new Error(`Document ${asset.assetId} not found in workspace ${ACTIVE_WORKSPACE_ID}.`);
-        }
-        if (!fs.existsSync(resolvedPath) || !fs.statSync(resolvedPath).isFile()) {
-            throw new Error(`Document ${asset.assetId} not found in workspace ${ACTIVE_WORKSPACE_ID}.`);
-        }
-        return fs.readFileSync(resolvedPath);
-    };
-    const buildDocumentDownloadUrl = (asset) => {
-        const safeName = sanitizeFilenameForPath(asset.originalFilename
-            || asset.logicalName
-            || path.basename(String(asset.storageKey || '').trim())
-            || 'document.txt', 'document.txt');
-        return `/api/taskforce/documents/${encodeURIComponent(String(asset.assetId || '').trim())}/content?download=1&filename=${encodeURIComponent(safeName)}`;
-    };
-    const resolveAttachmentLogicalFilename = (attachmentInput, assetOverride) => {
-        const attachment = toTaskAttachmentRecord(attachmentInput);
-        const asset = assetOverride ?? getAttachmentAssetRecord(attachment);
-        const candidate = String(attachment.originalFilename
-            || asset?.originalFilename
-            || attachment.displayName
-            || asset?.logicalName
-            || '').trim();
-        if (candidate) {
-            return sanitizeFilenameForPath(candidate);
-        }
-        const storageKey = normalizeAttachmentStorageKey(attachment.path, attachment.fsPath);
-        return sanitizeFilenameForPath(storageKey ? path.basename(storageKey) : '', 'attachment.txt');
-    };
-    const resolveCanonicalOverwriteTarget = (task, filenameRaw) => {
-        const requestedFilename = sanitizeFilenameForPath(filenameRaw);
-        const existingAttachments = Array.isArray(task.attachments) ? task.attachments : [];
-        for (let index = 0; index < existingAttachments.length; index++) {
-            const attachment = toTaskAttachmentRecord(existingAttachments[index]);
-            const asset = getAttachmentAssetRecord(attachment);
-            if (!asset || asset.deletedAt || asset.storageProvider === 'external')
-                continue;
-            const descriptor = describeTaskAttachment(task.id, attachment);
-            if (descriptor.source !== 'canonical')
-                continue;
-            const logicalFilename = resolveAttachmentLogicalFilename(attachment, asset);
-            if (logicalFilename !== requestedFilename)
-                continue;
-            const relativePath = toPosixPath(path.relative(PROJECT_ROOT, path.resolve(basePath, asset.storageKey)));
-            return {
-                index,
-                attachment,
-                asset,
-                descriptor,
-                relativePath,
-                absolutePath: path.resolve(basePath, asset.storageKey),
-                logicalFilename,
-            };
-        }
-        return null;
-    };
-    const ensureCanonicalTaskAttachment = (relativePathRaw, taskIdRaw, captionRaw, timestampRaw, role, options) => {
-        if (!workspaceAssetStore)
-            return null;
-        const relativePath = String(relativePathRaw || '').trim();
-        const taskId = String(taskIdRaw || '').trim();
-        if (!relativePath || !taskId)
-            return null;
-        const absolutePath = path.resolve(PROJECT_ROOT, relativePath);
-        if (!fs.existsSync(absolutePath) || !fs.statSync(absolutePath).isFile())
-            return null;
-        const storageKey = relativePath.replace(/^\.taskforce\//, '').trim() || relativePath;
-        const buffer = fs.readFileSync(absolutePath);
-        const stats = fs.statSync(absolutePath);
-        const mimeType = inferMimeTypeFromPath(relativePath);
-        const kind = inferAssetKind(relativePath, mimeType);
-        const timestamp = String(timestampRaw || new Date().toISOString()).trim() || new Date().toISOString();
-        const existing = workspaceAssetStore.getByStorageKey(storageKey, ACTIVE_WORKSPACE_ID);
-        const originalFilename = sanitizeFilenameForPath(options?.originalFilename || existing?.originalFilename || path.basename(relativePath));
-        const logicalName = sanitizeDisplayName(options?.logicalName || existing?.logicalName || originalFilename, originalFilename);
-        const asset = workspaceAssetStore.upsertAsset({
-            assetId: options?.assetId || existing?.assetId || `asset-${randomUUID().replace(/-/g, '')}`,
-            workspaceId: ACTIVE_WORKSPACE_ID,
-            kind,
-            logicalName,
-            originalFilename,
-            mimeType,
-            storageProvider: 'local',
-            storageKey,
-            contentSha256: createHash('sha256').update(buffer).digest('hex'),
-            sizeBytes: stats.size,
-            documentId: kind === 'document' ? (options?.documentId || existing?.documentId || `doc-${randomUUID().replace(/-/g, '')}`) : null,
-            version: kind === 'document' ? Math.max(1, Number(existing?.version || 0) + 1) : null,
-            isLatest: true,
-            scanStatus: options?.scanStatus || existing?.scanStatus || 'clean',
-            scanEngine: options?.scanEngine !== undefined ? options.scanEngine : (existing?.scanEngine || null),
-            scanDetails: options?.scanDetails !== undefined ? options.scanDetails : (existing?.scanDetails || null),
-            createdByUserId: options?.createdByUserId !== undefined ? options.createdByUserId : (existing?.createdByUserId || null),
-            createdAt: options?.createdAt || existing?.createdAt || timestamp,
-            updatedAt: timestamp,
-            deletedAt: null,
-            purgeAfter: null
-        });
-        workspaceAssetStore.upsertLink({
-            workspaceId: ACTIVE_WORKSPACE_ID,
-            assetId: asset.assetId,
-            taskId,
-            role,
-            displayName: kind === 'document' ? null : (captionRaw || null),
-            updatedAt: timestamp,
-            deletedAt: null
-        });
-        return asset;
-    };
+    const documentHelpers = createDocumentHelpers({
+        activeWorkspaceId: ACTIVE_WORKSPACE_ID,
+        workspaceAssetStore,
+        getDocumentReferenceLabel,
+        parseDocumentReference,
+        isTextReadableMimeType,
+    });
+    const canonicalAssetHelpers = createCanonicalAssetHelpers({
+        activeWorkspaceId: ACTIVE_WORKSPACE_ID,
+        projectRoot: PROJECT_ROOT,
+        basePath,
+        workspaceAssetStore,
+        objectStorageClient,
+        sanitizeFilenameForPath,
+        sanitizeDisplayName,
+        toPosixPath,
+        inferMimeTypeFromPath,
+        inferAssetKind,
+        buildCanonicalWorkspaceAssetRelativePath,
+    });
+    const taskAttachmentHelpers = createTaskAttachmentHelpers({
+        activeWorkspaceId: ACTIVE_WORKSPACE_ID,
+        workspaceAssetStore,
+        getImageReferenceLabel,
+        getDocumentReferenceLabel,
+        inferMimeTypeFromPath,
+        inferAssetKind,
+        isTextReadableMimeType,
+        isValidCanonicalDocumentAsset,
+        canonicalAssetHelpers,
+        documentHelpers,
+    });
     const server = new Server({
         name: options.serverName || `taskforce-${PROJECT_NAME}`,
         version: MCP_SERVER_VERSION,
@@ -669,75 +411,9 @@ export function createTaskforceMcpServer(options = {}) {
         }
         return { id: task.id, task };
     }
-    function buildDocumentDescriptor(asset) {
-        return {
-            assetId: asset.assetId,
-            documentId: asset.documentId ?? null,
-            referenceNumber: typeof asset.referenceNumber === 'number' ? asset.referenceNumber : null,
-            referenceLabel: getDocumentReferenceLabel(asset),
-            logicalName: asset.logicalName ?? null,
-            originalFilename: asset.originalFilename ?? null,
-            version: typeof asset.version === 'number' ? asset.version : null,
-            storageKey: asset.storageKey ?? null,
-            mimeType: asset.mimeType ?? null,
-            sizeBytes: typeof asset.sizeBytes === 'number' ? asset.sizeBytes : null,
-            updatedAt: asset.updatedAt ?? null,
-            apiUrl: `/api/taskforce/documents/${encodeURIComponent(String(asset.assetId || '').trim())}/content`,
-        };
-    }
-    function buildDocumentReadHint(asset) {
-        const preferredIdentifier = getDocumentReferenceLabel(asset)
-            || (typeof asset.documentId === 'string' && asset.documentId.trim().length > 0 ? asset.documentId.trim() : null)
-            || String(asset.assetId || '').trim();
-        const readable = isTextReadableMimeType(asset.mimeType || '');
-        if (readable) {
-            return {
-                available: true,
-                nextTool: 'read_document_content',
-                suggestedArgs: { documentId: preferredIdentifier },
-                guidance: 'To read the document body, call read_document_content with this documentId.',
-                reviewNext: {
-                    helperTool: 'review_document',
-                    listTool: 'get_document_review_sessions',
-                    createTool: 'create_document_review_session',
-                    commentTool: 'add_document_review_comment',
-                    guidance: 'After reading the document body, prefer review_document for a lower-friction review flow, or use get_document_review_sessions/create_document_review_session and add_document_review_comment directly.'
-                }
-            };
-        }
-        return {
-            available: false,
-            nextTool: 'read_document_content',
-            suggestedArgs: { documentId: preferredIdentifier },
-            guidance: 'This document is not inline-readable as text. Call read_document_content to get the structured download/reference response.',
-            reviewNext: {
-                helperTool: 'review_document',
-                listTool: 'get_document_review_sessions',
-                createTool: 'create_document_review_session',
-                commentTool: 'add_document_review_comment',
-                guidance: 'After inspecting the document access response, prefer review_document for a lower-friction review flow, or use get_document_review_sessions/create_document_review_session and add_document_review_comment directly.'
-            },
-            reason: 'binary_file',
-        };
-    }
-    function buildCanonicalDocumentAttachmentHint(asset) {
-        const preferredIdentifier = getDocumentReferenceLabel(asset)
-            || (typeof asset.documentId === 'string' && asset.documentId.trim().length > 0 ? asset.documentId.trim() : null)
-            || String(asset.assetId || '').trim();
-        if (!preferredIdentifier) {
-            return null;
-        }
-        const readable = isTextReadableMimeType(asset.mimeType || '');
-        return {
-            documentId: typeof asset.documentId === 'string' && asset.documentId.trim().length > 0 ? asset.documentId.trim() : null,
-            preferredNextTool: 'get_document',
-            preferredWorkflow: 'canonical_document',
-            suggestedArgs: { documentId: preferredIdentifier },
-            guidance: readable
-                ? 'This attachment is a canonical document. Prefer get_document, then read_document_content, for ongoing document work and review.'
-                : 'This attachment is a canonical document. Prefer get_document for metadata and review context, then read_document_content for the structured content/download response.',
-        };
-    }
+    const buildDocumentDescriptor = documentHelpers.buildDocumentDescriptor;
+    const buildDocumentReadHint = documentHelpers.buildDocumentReadHint;
+    const buildCanonicalDocumentAttachmentHint = documentHelpers.buildCanonicalDocumentAttachmentHint;
     function searchImageAssets(queryRaw, options) {
         const query = typeof queryRaw === 'string' ? queryRaw.trim().toLowerCase() : '';
         if (!query) {
@@ -796,65 +472,7 @@ export function createTaskforceMcpServer(options = {}) {
             .sort((a, b) => b.score - a.score || String(b.asset.updatedAt || '').localeCompare(String(a.asset.updatedAt || '')))
             .slice(0, limit);
     }
-    function searchDocumentAssets(queryRaw, options) {
-        const query = typeof queryRaw === 'string' ? queryRaw.trim().toLowerCase() : '';
-        if (!query) {
-            throw new Error('query is required');
-        }
-        if (!workspaceAssetStore) {
-            throw new Error('Workspace asset store unavailable.');
-        }
-        const requestedLimit = Number(options?.limit);
-        const limit = Number.isFinite(requestedLimit)
-            ? Math.max(1, Math.min(50, Math.trunc(requestedLimit)))
-            : 10;
-        const normalize = (value) => typeof value === 'string' ? value.trim().toLowerCase() : '';
-        const tokenize = (value) => normalize(value).split(/[^a-z0-9]+/i).filter(Boolean);
-        const allDocuments = workspaceAssetStore.listAllByWorkspace(ACTIVE_WORKSPACE_ID, { kind: 'document' });
-        const scoredMatches = allDocuments.flatMap((asset) => {
-            if (asset.deletedAt)
-                return [];
-            const fields = [
-                { label: 'referenceLabel', value: getDocumentReferenceLabel(asset) || '' },
-                { label: 'documentId', value: asset.documentId || '' },
-                { label: 'logicalName', value: asset.logicalName || '' },
-                { label: 'originalFilename', value: asset.originalFilename || '' },
-                { label: 'assetId', value: asset.assetId || '' },
-            ];
-            let score = 0;
-            const matchedOn = new Set();
-            for (const field of fields) {
-                const normalized = normalize(field.value);
-                if (!normalized)
-                    continue;
-                if (normalized === query) {
-                    score += field.label === 'referenceLabel' || field.label === 'documentId' ? 120 : 90;
-                    matchedOn.add(field.label);
-                    continue;
-                }
-                if (normalized.startsWith(query)) {
-                    score += field.label === 'logicalName' || field.label === 'originalFilename' ? 60 : 50;
-                    matchedOn.add(field.label);
-                    continue;
-                }
-                if (normalized.includes(query)) {
-                    score += 35;
-                    matchedOn.add(field.label);
-                    continue;
-                }
-                if (tokenize(field.value).some((token) => token.startsWith(query))) {
-                    score += 20;
-                    matchedOn.add(field.label);
-                }
-            }
-            if (score <= 0)
-                return [];
-            return [{ asset, matchedOn: Array.from(matchedOn), score }];
-        });
-        return scoredMatches
-            .sort((a, b) => b.score - a.score || String(b.asset.updatedAt || '').localeCompare(String(a.asset.updatedAt || '')))
-            .slice(0, limit);
-    }
+    const searchDocumentAssets = documentHelpers.searchDocumentAssets;
     function buildImageDescriptor(asset) {
         return {
             assetId: asset.assetId,
@@ -869,32 +487,7 @@ export function createTaskforceMcpServer(options = {}) {
             apiUrl: `/api/taskforce/context/${encodeURIComponent(String(asset.storageKey || '').trim())}`,
         };
     }
-    function resolveDocumentAssetByIdentifierOrThrow(documentIdentifier, options) {
-        const normalizedValue = typeof documentIdentifier === 'string' ? documentIdentifier.trim() : '';
-        if (!normalizedValue) {
-            throw new Error('documentId is required');
-        }
-        if (!workspaceAssetStore) {
-            throw new Error('Workspace asset store unavailable.');
-        }
-        const matchesDocumentAsset = (asset) => Boolean(asset && asset.kind === 'document' && asset.deletedAt == null);
-        const directAsset = workspaceAssetStore.get(normalizedValue, ACTIVE_WORKSPACE_ID);
-        if (matchesDocumentAsset(directAsset)) {
-            return directAsset;
-        }
-        const documentAssets = workspaceAssetStore.listAllByWorkspace(ACTIVE_WORKSPACE_ID, { kind: 'document' });
-        const referenceNumber = parseDocumentReference(normalizedValue);
-        const matchedAsset = documentAssets.find((asset) => asset.documentId === normalizedValue)
-            || (referenceNumber
-                ? documentAssets.find((asset) => asset.referenceNumber === referenceNumber && asset.isLatest)
-                    || documentAssets.find((asset) => asset.referenceNumber === referenceNumber)
-                : null);
-        if (matchesDocumentAsset(matchedAsset)) {
-            return matchedAsset;
-        }
-        throw new Error(options?.notFoundMessage
-            || `Document ${normalizedValue} not found in workspace ${ACTIVE_WORKSPACE_ID}. If you only know a keyword, filename, or rough title, call search_documents first.`);
-    }
+    const resolveDocumentAssetByIdentifierOrThrow = documentHelpers.resolveDocumentAssetByIdentifierOrThrow;
     function resolveImageAssetByIdentifierOrThrow(imageIdentifier, options) {
         const normalizedValue = typeof imageIdentifier === 'string' ? imageIdentifier.trim() : '';
         if (!normalizedValue) {
@@ -1419,13 +1012,91 @@ export function createTaskforceMcpServer(options = {}) {
             },
         });
     }
+    function logMcpStructuredEvent(level, event, details) {
+        const payload = {
+            event,
+            runtimeMode,
+            workspaceId: ACTIVE_WORKSPACE_ID,
+            requestId: auditRequestId,
+            ...details,
+        };
+        const logger = level === 'error'
+            ? console.error
+            : level === 'warn'
+                ? console.warn
+                : console.info;
+        logger(`[Taskforce MCP] ${JSON.stringify(payload)}`);
+    }
+    function logMcpReadObservation(toolName, startedAtMs, details = {}) {
+        const durationMs = Date.now() - startedAtMs;
+        const shouldLog = runtimeMode === 'cloud'
+            ? toolName === 'get_current_profile' || toolName === 'list_tasks' || durationMs >= 150
+            : durationMs >= 250;
+        if (!shouldLog)
+            return;
+        logMcpStructuredEvent('info', 'tool_read_complete', {
+            toolName,
+            durationMs,
+            ...details,
+        });
+    }
     /**
      * Helpers
      */
-    const taskforceManagedAttachmentSourceRoots = [
-        path.resolve(basePath, 'tmp'),
-        path.resolve(basePath, 'artifacts'),
-    ];
+    function listExistingAttachmentSourceRoots(candidateRoots) {
+        const seen = new Set();
+        const results = [];
+        for (const candidate of candidateRoots) {
+            const trimmed = String(candidate || '').trim();
+            if (!trimmed)
+                continue;
+            const resolved = path.resolve(trimmed);
+            if (!fs.existsSync(resolved))
+                continue;
+            let realPath;
+            try {
+                realPath = fs.realpathSync(resolved);
+            }
+            catch {
+                continue;
+            }
+            if (!fs.statSync(realPath).isDirectory())
+                continue;
+            if (seen.has(realPath))
+                continue;
+            seen.add(realPath);
+            results.push(realPath);
+        }
+        return results;
+    }
+    function listConfiguredAttachmentSourceRoots() {
+        const configured = String(process.env.TASKFORCE_ALLOWED_ATTACHMENT_SOURCE_ROOTS || '').trim();
+        if (!configured)
+            return [];
+        return listExistingAttachmentSourceRoots(configured
+            .split(path.delimiter)
+            .map((entry) => entry.trim())
+            .filter(Boolean));
+    }
+    function listKnownAgentWorkspaceRoots() {
+        const openClawRoot = path.join(os.homedir(), '.openclaw');
+        if (!fs.existsSync(openClawRoot))
+            return [];
+        const entries = fs.readdirSync(openClawRoot, { withFileTypes: true });
+        const workspaceRoots = entries
+            .filter((entry) => entry.isDirectory() && /^workspace-/i.test(entry.name))
+            .map((entry) => path.join(openClawRoot, entry.name));
+        return listExistingAttachmentSourceRoots(workspaceRoots);
+    }
+    function getApprovedAttachmentSourceRoots(projectRootReal) {
+        return listExistingAttachmentSourceRoots([
+            projectRootReal,
+            path.resolve(basePath, 'tmp'),
+            path.resolve(basePath, 'artifacts'),
+            ...listConfiguredAttachmentSourceRoots(),
+            ...listKnownAgentWorkspaceRoots(),
+        ]);
+    }
     function renderTaskTable(tasks) {
         if (tasks.length === 0)
             return "No tasks found.";
@@ -1458,9 +1129,7 @@ export function createTaskforceMcpServer(options = {}) {
         return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
     }
     function isApprovedAttachmentSourcePath(filePath, projectRootReal) {
-        if (isWithinRoot(filePath, projectRootReal))
-            return true;
-        return taskforceManagedAttachmentSourceRoots.some((root) => isWithinRoot(filePath, root));
+        return getApprovedAttachmentSourceRoots(projectRootReal).some((root) => isWithinRoot(filePath, root));
     }
     function toPosixPath(filePath) {
         return filePath.split(path.sep).join('/');
@@ -1706,11 +1375,20 @@ export function createTaskforceMcpServer(options = {}) {
     async function flushScheduledResourceInvalidations() {
         if (pendingResourceInvalidations.size === 0)
             return;
+        const startedAtMs = Date.now();
         const uris = Array.from(pendingResourceInvalidations);
         pendingResourceInvalidations.clear();
         for (const uri of uris) {
             await notifyResourceUpdatedIfSubscribed(uri);
         }
+        const durationMs = Date.now() - startedAtMs;
+        if (runtimeMode === 'cloud' || durationMs >= 100 || uris.length >= 3) {
+            logMcpStructuredEvent('info', 'resource_invalidation_flush', {
+                uriCount: uris.length,
+                durationMs,
+                uris,
+            });
+        }
     }
     function scheduleResourceMutation(options) {
         const uris = collectResourceMutationUris(options);
@@ -3059,7 +2737,7 @@ export function createTaskforceMcpServer(options = {}) {
             {
                 name: "save_task_attachment",
                 description: describeTool(runtimeMode === 'cloud'
-                    ? "Save generated content into a task attachment and link it to the task. Use this when an agent creates notes, reports, or artifacts that should live with the task instead of remaining only in chat. For cloud MCP, AI-authored markdown/text should usually be passed inline via content rather than sourcePath. When overwrite=true, this replaces an existing canonical attachment with the same logical filename in place. External URL attachments are never overwrite targets; if no matching canonical attachment exists, a new attachment is created."
+                    ? "Save generated content into a task attachment and link it to the task. Use this when an agent creates notes, reports, or artifacts that should live with the task instead of remaining only in chat. For cloud MCP, use inline content for AI-authored markdown/text, or use sourcePath when the file already exists inside the repo, a Taskforce-managed attachment source, or an approved agent workspace root. When overwrite=true, this replaces an existing canonical attachment with the same logical filename in place. External URL attachments are never overwrite targets; if no matching canonical attachment exists, a new attachment is created."
                     : "Save generated content or copy a file into a task-specific attachment and link it to the task. Use this when an agent creates notes, reports, or artifacts that should live with the task instead of remaining only in chat. When overwrite=true, this replaces an existing canonical attachment with the same logical filename in place. External URL attachments are never overwrite targets; if no matching canonical attachment exists, a new attachment is created."),
                 inputSchema: {
                     type: "object",
@@ -3067,7 +2745,7 @@ export function createTaskforceMcpServer(options = {}) {
                         id: { type: "string", description: "Task ID" },
                         filename: { type: "string", description: "Target filename for the task attachment." },
                         content: { type: "string", description: runtimeMode === 'cloud' ? "Text/markdown file content to save. For cloud MCP, use this for AI-authored markdown/text attachments." : "Text/markdown file content to save. Provide either content or sourcePath." },
-                        sourcePath: { type: "string", description: runtimeMode === 'cloud' ? "Project-relative or absolute source file path to copy (local runtime only today). For cloud MCP, prefer inline content for AI-authored markdown/text." : "Project-relative or absolute source file path to copy. Provide either sourcePath or content." },
+                        sourcePath: { type: "string", description: runtimeMode === 'cloud' ? "Project-relative or absolute source file path to copy. In cloud MCP this must resolve inside the repo, a Taskforce-managed attachment source, or an approved agent workspace root. Use content instead for AI-authored markdown/text." : "Project-relative or absolute source file path to copy. Provide either sourcePath or content." },
                         caption: { type: "string", description: "Optional label shown in task context" },
                         overwrite: { type: "boolean", description: "Overwrite the destination file when it already exists (default: false)." }
                     },
@@ -3318,6 +2996,7 @@ export function createTaskforceMcpServer(options = {}) {
             assertResolvedProfileForMutatingTool(name);
             switch (name) {
                 case "list_tasks": {
+                    const startedAtMs = Date.now();
                     const { format = "markdown", category, status, openOnly = false, assignee, priority, type, sort = "created", order = "desc", limit } = args;
                     let data = core.listTasks(ACTIVE_WORKSPACE_ID);
                     let tasks = data.tasks;
@@ -3360,7 +3039,21 @@ export function createTaskforceMcpServer(options = {}) {
                     // Strip verbose detail fields — descriptions, comments, events, and derived
                     // activity are omitted from list responses to keep context window usage
                     // manageable. Use get_task to retrieve full details for a specific task.
-                    const slimTasks = tasks.map(({ description, comments, taskEvents, activity, createdByActor, assigneeActor, ...rest }) => rest);
+                    const slimTasks = tasks.map(({ description, comments, taskEvents, activity, createdByActor, assigneeActor, attachments, checklistItems, ...rest }) => rest);
+                    logMcpReadObservation('list_tasks', startedAtMs, {
+                        format,
+                        totalTasks: data.tasks.length,
+                        returnedTasks: slimTasks.length,
+                        filtered: slimTasks.length !== data.tasks.length,
+                        openOnly,
+                        hasAssigneeFilter: Boolean(assignee),
+                        hasStatusFilter: Boolean(status),
+                        hasCategoryFilter: Boolean(category),
+                        hasTypeFilter: Boolean(type),
+                        hasPriorityFilter: priority !== undefined,
+                        sort,
+                        order,
+                    });
                     if (format === "json") {
                         return {
                             content: [{ type: "text", text: JSON.stringify(slimTasks, null, 2) }],
@@ -3428,6 +3121,7 @@ export function createTaskforceMcpServer(options = {}) {
                     };
                 }
                 case "get_current_profile": {
+                    const startedAtMs = Date.now();
                     const { profileToken } = args;
                     ensureResolvedProfileForSessionBootstrap();
                     let profile = activeAiProfileId
@@ -3444,6 +3138,13 @@ export function createTaskforceMcpServer(options = {}) {
                         }
                         bindingSource = 'token_lookup';
                     }
+                    logMcpReadObservation('get_current_profile', startedAtMs, {
+                        identityBound: Boolean(activeAiProfileId),
+                        bindingSource,
+                        writeReady: Boolean(profile),
+                        profileResolved: Boolean(profile),
+                        usedProfileTokenLookup: !activeAiProfileId && typeof profileToken === 'string' && profileToken.trim().length > 0,
+                    });
                     return {
                         content: [{
                                 type: "text",
@@ -3782,7 +3483,7 @@ export function createTaskforceMcpServer(options = {}) {
                                 text: JSON.stringify({
                                     taskId: task.id,
                                     referenceLabel: task.referenceLabel || getTaskReferenceLabel(task),
-                                    attachments: listTaskAttachmentDescriptors(task)
+                                    attachments: taskAttachmentHelpers.listTaskAttachmentDescriptors(task)
                                 }, null, 2)
                             }],
                     };
@@ -3793,7 +3494,7 @@ export function createTaskforceMcpServer(options = {}) {
                     if (!task) {
                         throw new Error(`Task ${taskId} not found`);
                     }
-                    const attachments = listTaskAttachmentDescriptors(task);
+                    const attachments = taskAttachmentHelpers.listTaskAttachmentDescriptors(task);
                     const attachment = attachments.find((entry) => entry.attachmentId === attachmentId);
                     if (!attachment) {
                         throw new Error(`Attachment ${attachmentId} not found on task ${taskId}`);
@@ -3818,7 +3519,7 @@ export function createTaskforceMcpServer(options = {}) {
                                         taskId: task.id,
                                         attachment,
                                         format: "download",
-                                        downloadUrl: buildAttachmentDownloadUrl(attachment),
+                                        downloadUrl: canonicalAssetHelpers.buildAttachmentDownloadUrl(attachment),
                                         reason: attachment.source === 'external' ? 'external_reference' : 'requested_download'
                                     }, null, 2)
                                 }],
@@ -3832,14 +3533,14 @@ export function createTaskforceMcpServer(options = {}) {
                                         taskId: task.id,
                                         attachment,
                                         format: "download",
-                                        downloadUrl: buildAttachmentDownloadUrl(attachment),
+                                        downloadUrl: canonicalAssetHelpers.buildAttachmentDownloadUrl(attachment),
                                         reason: attachment.source === 'external' ? 'external_reference' : 'binary_file'
                                     }, null, 2)
                                 }],
                         };
                     }
                     const resolvedMaxChars = Math.max(1, Math.floor(Number(maxChars || 200000)));
-                    const buffer = await readCanonicalAttachmentBuffer(task.id, attachment);
+                    const buffer = await canonicalAssetHelpers.readCanonicalAttachmentBuffer(task.id, attachment);
                     const content = buffer.toString('utf8');
                     if (content.length > resolvedMaxChars) {
                         throw new Error('Attachment exceeds maxChars limit for inline read');
@@ -4026,7 +3727,7 @@ export function createTaskforceMcpServer(options = {}) {
                                     text: JSON.stringify({
                                         document,
                                         format: "download",
-                                        downloadUrl: buildDocumentDownloadUrl(asset),
+                                        downloadUrl: canonicalAssetHelpers.buildDocumentDownloadUrl(asset),
                                         reason: "requested_download"
                                     }, null, 2)
                                 }],
@@ -4039,14 +3740,14 @@ export function createTaskforceMcpServer(options = {}) {
                                     text: JSON.stringify({
                                         document,
                                         format: "download",
-                                        downloadUrl: buildDocumentDownloadUrl(asset),
+                                        downloadUrl: canonicalAssetHelpers.buildDocumentDownloadUrl(asset),
                                         reason: "binary_file"
                                     }, null, 2)
                                 }],
                         };
                     }
                     const resolvedMaxChars = Math.max(1, Math.floor(Number(maxChars || 200000)));
-                    const buffer = await readCanonicalDocumentBuffer(asset);
+                    const buffer = await canonicalAssetHelpers.readCanonicalDocumentBuffer(asset);
                     const content = buffer.toString('utf8');
                     if (content.length > resolvedMaxChars) {
                         throw new Error('Document exceeds maxChars limit for inline read');
@@ -5281,9 +4982,6 @@ export function createTaskforceMcpServer(options = {}) {
                     if (hasContent === hasSourcePath) {
                         throw new Error("Provide exactly one of: content or sourcePath");
                     }
-                    if (runtimeMode === 'cloud' && hasSourcePath) {
-                        throw new Error("Cloud MCP does not support sourcePath for save_task_attachment yet. For AI-authored markdown or text, resend the attachment using inline content instead.");
-                    }
                     const now = new Date().toISOString();
                     const safeCaption = typeof caption === 'string' && caption.trim().length > 0
                         ? caption.trim()
@@ -5291,11 +4989,11 @@ export function createTaskforceMcpServer(options = {}) {
                     const safeFilename = sanitizeFilenameForPath(filename);
                     const { projectRoot, basePath } = core.getPaths();
                     const overwriteTarget = overwrite === true
-                        ? resolveCanonicalOverwriteTarget(task, safeFilename)
+                        ? canonicalAssetHelpers.resolveCanonicalOverwriteTarget(task, safeFilename, taskAttachmentHelpers.describeTaskAttachment)
                         : null;
                     const canonicalAsset = overwriteTarget
                         ? null
-                        : buildCanonicalWorkspaceAssetRelativePath({
+                        : canonicalAssetHelpers.buildCanonicalWorkspaceAssetRelativePath({
                             workspaceIdRaw: ACTIVE_WORKSPACE_ID,
                             kind: inferAssetKind(safeFilename, inferMimeTypeFromPath(safeFilename)),
                             filename: safeFilename
@@ -5318,7 +5016,7 @@ export function createTaskforceMcpServer(options = {}) {
                         const sourceReal = fs.realpathSync(sourceResolved);
                         const projectRootReal = fs.realpathSync(projectRoot);
                         if (!isApprovedAttachmentSourcePath(sourceReal, projectRootReal)) {
-                            throw new Error("sourcePath must be within project root or a Taskforce-managed attachment source");
+                            throw new Error("sourcePath must be within project root, a Taskforce-managed attachment source, or an approved agent workspace root");
                         }
                         if (!fs.statSync(sourceReal).isFile()) {
                             throw new Error(`Path is not a file: ${trimmedSource}`);
@@ -5340,7 +5038,7 @@ export function createTaskforceMcpServer(options = {}) {
                     const persistedCaption = isMarkdownDocument
                         ? canonicalName
                         : (safeCaption || overwriteTarget?.attachment.caption || safeFilename);
-                    const asset = ensureCanonicalTaskAttachment(relativePath, id, persistedCaption, now, 'attachment', {
+                    const asset = canonicalAssetHelpers.ensureCanonicalTaskAttachment(relativePath, id, persistedCaption, now, 'attachment', {
                         originalFilename: safeFilename,
                         logicalName: isMarkdownDocument ? canonicalName : safeFilename,
                         ...(overwriteTarget
@@ -5356,7 +5054,7 @@ export function createTaskforceMcpServer(options = {}) {
                             : {})
                     });
                     const attachment = {
-                        path: overwriteTarget?.attachment.path || (asset?.kind === 'document' && isCanonicalDocumentAssetRecord(asset) && asset.assetId
+                        path: overwriteTarget?.attachment.path || (asset?.kind === 'document' && isValidCanonicalDocumentAsset(asset) && asset.assetId
                             ? `/api/taskforce/documents/${encodeURIComponent(asset.assetId)}/content`
                             : `/api/taskforce/context/${encodeURIComponent((canonicalAsset || { relativePath: overwriteTarget?.descriptor.fsPath || '' }).relativePath)}`),
                         fsPath: overwriteTarget?.attachment.fsPath || canonicalAsset?.relativePath || overwriteTarget?.descriptor.fsPath,
@@ -5426,7 +5124,7 @@ export function createTaskforceMcpServer(options = {}) {
                         throw new Error('attachmentId is required');
                     const { id, task } = resolveTaskByIdentifierOrThrow(inputTaskId);
                     const existing = Array.isArray(task.attachments) ? task.attachments : [];
-                    const descriptors = listTaskAttachmentDescriptors(task);
+                    const descriptors = taskAttachmentHelpers.listTaskAttachmentDescriptors(task);
                     const targetIndex = descriptors.findIndex((entry) => entry.attachmentId === attachmentId);
                     if (targetIndex < 0) {
                         throw new Error(`Attachment ${attachmentId} not found on task ${inputTaskId}`);