@taskforcehq/taskforce 0.3.302 → 0.3.304

package/dist/mcp/documentHelpers.d.ts

@@ -0,0 +1,100 @@
+import type { WorkspaceAssetEntry, WorkspaceAssetStore } from '../storage/workspaceAssetStore.js';
+export interface DocumentHelpersDeps {
+    activeWorkspaceId: string;
+    workspaceAssetStore: WorkspaceAssetStore | null;
+    getDocumentReferenceLabel: (asset: {
+        assetId: string;
+        documentId?: string | null;
+        referenceNumber?: number | null;
+    }) => string | null;
+    parseDocumentReference: (value: string) => number | null;
+    isTextReadableMimeType: (mimeTypeRaw: string) => boolean;
+}
+export declare function createDocumentHelpers(deps: DocumentHelpersDeps): {
+    buildDocumentDescriptor: (asset: {
+        assetId: string;
+        documentId: string | null;
+        referenceNumber?: number | null;
+        kind?: string | null;
+        logicalName?: string | null;
+        originalFilename?: string | null;
+        version?: number | null;
+        storageKey?: string | null;
+        mimeType?: string | null;
+        sizeBytes?: number | null;
+        updatedAt?: string | null;
+    }) => {
+        assetId: string;
+        documentId: string | null;
+        referenceNumber: number | null;
+        referenceLabel: string | null;
+        logicalName: string | null;
+        originalFilename: string | null;
+        version: number | null;
+        storageKey: string | null;
+        mimeType: string | null;
+        sizeBytes: number | null;
+        updatedAt: string | null;
+        apiUrl: string;
+    };
+    buildDocumentReadHint: (asset: {
+        assetId: string;
+        documentId: string | null;
+        referenceNumber?: number | null;
+        mimeType?: string | null;
+    }) => {
+        available: boolean;
+        nextTool: string;
+        suggestedArgs: {
+            documentId: string;
+        };
+        guidance: string;
+        reviewNext: {
+            helperTool: string;
+            listTool: string;
+            createTool: string;
+            commentTool: string;
+            guidance: string;
+        };
+        reason?: undefined;
+    } | {
+        available: boolean;
+        nextTool: string;
+        suggestedArgs: {
+            documentId: string;
+        };
+        guidance: string;
+        reviewNext: {
+            helperTool: string;
+            listTool: string;
+            createTool: string;
+            commentTool: string;
+            guidance: string;
+        };
+        reason: string;
+    };
+    buildCanonicalDocumentAttachmentHint: (asset: {
+        assetId: string;
+        documentId: string | null;
+        referenceNumber?: number | null;
+        mimeType?: string | null;
+    }) => {
+        documentId: string | null;
+        preferredNextTool: string;
+        preferredWorkflow: string;
+        suggestedArgs: {
+            documentId: string;
+        };
+        guidance: string;
+    } | null;
+    searchDocumentAssets: (queryRaw: unknown, options?: {
+        limit?: unknown;
+    }) => Array<{
+        asset: WorkspaceAssetEntry;
+        matchedOn: string[];
+        score: number;
+    }>;
+    resolveDocumentAssetByIdentifierOrThrow: (documentIdentifier: unknown, options?: {
+        notFoundMessage?: string;
+    }) => WorkspaceAssetEntry;
+};

package/dist/mcp/documentHelpers.js

@@ -0,0 +1,161 @@
+export function createDocumentHelpers(deps) {
+    const buildDocumentDescriptor = (asset) => ({
+        assetId: asset.assetId,
+        documentId: asset.documentId ?? null,
+        referenceNumber: typeof asset.referenceNumber === 'number' ? asset.referenceNumber : null,
+        referenceLabel: deps.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`,
+    });
+    const buildDocumentReadHint = (asset) => {
+        const preferredIdentifier = deps.getDocumentReferenceLabel(asset)
+            || (typeof asset.documentId === 'string' && asset.documentId.trim().length > 0 ? asset.documentId.trim() : null)
+            || String(asset.assetId || '').trim();
+        const readable = deps.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',
+        };
+    };
+    const buildCanonicalDocumentAttachmentHint = (asset) => {
+        const preferredIdentifier = deps.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 = deps.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 searchDocumentAssets = (queryRaw, options) => {
+        const query = typeof queryRaw === 'string' ? queryRaw.trim().toLowerCase() : '';
+        if (!query) {
+            throw new Error('query is required');
+        }
+        if (!deps.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 = deps.workspaceAssetStore.listAllByWorkspace(deps.activeWorkspaceId, { kind: 'document' });
+        const scoredMatches = allDocuments.flatMap((asset) => {
+            if (asset.deletedAt)
+                return [];
+            const fields = [
+                { label: 'referenceLabel', value: deps.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 resolveDocumentAssetByIdentifierOrThrow = (documentIdentifier, options) => {
+        const normalizedValue = typeof documentIdentifier === 'string' ? documentIdentifier.trim() : '';
+        if (!normalizedValue) {
+            throw new Error('documentId is required');
+        }
+        if (!deps.workspaceAssetStore) {
+            throw new Error('Workspace asset store unavailable.');
+        }
+        const matchesDocumentAsset = (asset) => Boolean(asset && asset.kind === 'document' && asset.deletedAt == null);
+        const directAsset = deps.workspaceAssetStore.get(normalizedValue, deps.activeWorkspaceId);
+        if (matchesDocumentAsset(directAsset)) {
+            return directAsset;
+        }
+        const documentAssets = deps.workspaceAssetStore.listAllByWorkspace(deps.activeWorkspaceId, { kind: 'document' });
+        const referenceNumber = deps.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 ${deps.activeWorkspaceId}. If you only know a keyword, filename, or rough title, call search_documents first.`);
+    };
+    return {
+        buildDocumentDescriptor,
+        buildDocumentReadHint,
+        buildCanonicalDocumentAttachmentHint,
+        searchDocumentAssets,
+        resolveDocumentAssetByIdentifierOrThrow,
+    };
+}