@taskforcehq/taskforce 0.3.303 → 0.3.305

package/dist/mcp/documentAssetRegistrar.js

@@ -0,0 +1,346 @@
+import { bindDomainTool } from './toolCatalog.js';
+function stringProperty(description, enumValues) {
+    return enumValues ? { type: 'string', description, enum: enumValues } : { type: 'string', description };
+}
+function numberProperty(description) {
+    return { type: 'number', description };
+}
+function booleanProperty(description) {
+    return { type: 'boolean', description };
+}
+function arrayProperty(description, items) {
+    return { type: 'array', description, items };
+}
+export function registerDocumentAssetTools(registerTool, executeTool) {
+    const register = (name, buildDescriptor) => {
+        registerTool({
+            name,
+            buildDescriptor: (context) => {
+                const descriptor = buildDescriptor(context);
+                return {
+                    name,
+                    description: descriptor.description,
+                    inputSchema: {
+                        type: 'object',
+                        properties: descriptor.inputSchema.properties,
+                        ...(descriptor.inputSchema.required ? { required: descriptor.inputSchema.required } : {}),
+                    },
+                };
+            },
+            handler: bindDomainTool(executeTool, name),
+        });
+    };
+    register('get_task_attachments', (context) => ({
+        description: context.describeTool('List attachment descriptors for one task. This returns metadata only; use read_task_attachment for file contents. For canonical documents, prefer get_document and read_document_content for the document-focused workflow.'),
+        inputSchema: {
+            properties: {
+                taskId: stringProperty('Task ID or task reference such as T-123.'),
+            },
+            required: ['taskId'],
+        },
+    }));
+    register('read_task_attachment', (context) => ({
+        description: context.describeTool('Read one task attachment by attachmentId. Prefer this tool over opening attachment path URLs directly. For a canonical document attachment, this response also points toward the document-specific workflow.'),
+        inputSchema: {
+            properties: {
+                taskId: stringProperty('Task ID or task reference such as T-123.'),
+                attachmentId: stringProperty('Attachment descriptor id from get_task_attachments.'),
+                maxChars: numberProperty('Optional max inline character count for readable text attachments.'),
+            },
+            required: ['taskId', 'attachmentId'],
+        },
+    }));
+    register('search_images', (context) => ({
+        description: context.describeTool('Search image assets by keyword, title, filename, caption, or I-123 reference. Use this before get_image when you only know a rough identifier.'),
+        inputSchema: {
+            properties: {
+                query: stringProperty('Search term for image lookup, including I-123 references.'),
+                limit: numberProperty('Max images to return.'),
+            },
+            required: ['query'],
+        },
+    }));
+    register('get_image', (context) => ({
+        description: context.describeTool('Get a single image by asset id or image reference such as I-123. Use this first when the user references an image, then use get_annotated_attachment_sessions and read_annotated_attachment_payload for annotation details.'),
+        inputSchema: {
+            properties: {
+                id: stringProperty('Image asset id or image reference such as I-123.'),
+            },
+            required: ['id'],
+        },
+    }));
+    register('search_documents', (context) => ({
+        description: context.describeTool('Search document assets by keyword, title, filename, caption, or D-123 reference. Use this before get_document when you only know a rough identifier. Search results guide the next step into get_document and read_document_content.'),
+        inputSchema: {
+            properties: {
+                query: stringProperty('Search term for document lookup, including D-123 references.'),
+                limit: numberProperty('Max documents to return.'),
+            },
+            required: ['query'],
+        },
+    }));
+    register('get_document', (context) => ({
+        description: context.describeTool('Get a single canonical document by asset id or document reference such as D-123. Use this first when the user references a document, then call read_document_content to inspect what it is reviewing.'),
+        inputSchema: {
+            properties: {
+                id: stringProperty('Document asset id or document reference such as D-123.'),
+            },
+            required: ['id'],
+        },
+    }));
+    register('read_document_content', (context) => ({
+        description: context.describeTool('Read the canonical document body for one document. Use this when an AI needs to inspect what it is reviewing before adding review comments.'),
+        inputSchema: {
+            properties: {
+                documentId: stringProperty('Document asset id or document reference such as D-123.'),
+                maxChars: numberProperty('Optional max inline character count for readable documents.'),
+            },
+            required: ['documentId'],
+        },
+    }));
+    register('get_annotated_attachment_sessions', (context) => ({
+        description: context.describeTool('List saved annotation sessions for one image. Use this after get_image when you need the saved annotation sessions before opening one payload.'),
+        inputSchema: {
+            properties: {
+                imageId: stringProperty('Image asset id or image reference such as I-123.'),
+            },
+            required: ['imageId'],
+        },
+    }));
+    register('read_annotated_attachment_payload', (context) => ({
+        description: context.describeTool('Read the structured payload for one annotated attachment session, including markers, geometry, and derived crop hints.'),
+        inputSchema: {
+            properties: {
+                sessionId: stringProperty('Annotated attachment session id.'),
+            },
+            required: ['sessionId'],
+        },
+    }));
+    register('create_annotated_attachment_session', (context) => ({
+        description: context.describeTool('Create a new annotation session for one image. Use this before adding markers when no saved session exists yet.'),
+        inputSchema: {
+            properties: {
+                imageId: stringProperty('Image asset id or image reference such as I-123.'),
+                title: stringProperty('Optional session title.'),
+            },
+            required: ['imageId'],
+        },
+    }));
+    register('update_annotated_attachment_session', (context) => ({
+        description: context.describeTool('Update an existing annotation session without changing its marker list directly.'),
+        inputSchema: {
+            properties: {
+                sessionId: stringProperty('Annotated attachment session id.'),
+                title: stringProperty('Updated session title.'),
+            },
+            required: ['sessionId'],
+        },
+    }));
+    register('delete_annotated_attachment_session', (context) => ({
+        description: context.describeTool('Delete an annotated attachment session when the whole session was created by mistake, rather than deleting markers one by one.'),
+        inputSchema: {
+            properties: {
+                sessionId: stringProperty('Annotated attachment session id.'),
+            },
+            required: ['sessionId'],
+        },
+    }));
+    register('review_image', (context) => ({
+        description: context.describeTool('Run a first-pass visual review workflow for one image and save the result into an annotation session when appropriate.'),
+        inputSchema: {
+            properties: {
+                imageId: stringProperty('Image asset id or image reference such as I-123.'),
+                prompt: stringProperty('Review instructions or focus areas for the first-pass review.'),
+            },
+            required: ['imageId', 'prompt'],
+        },
+    }));
+    register('add_annotated_attachment_marker', (context) => ({
+        description: context.describeTool('Add one marker to an annotation session using normalized 0..1 coordinates.'),
+        inputSchema: {
+            properties: {
+                sessionId: stringProperty('Annotated attachment session id.'),
+                type: stringProperty('Marker type.'),
+                x: numberProperty('Normalized x coordinate in the 0..1 range.'),
+                y: numberProperty('Normalized y coordinate in the 0..1 range.'),
+                width: numberProperty('Optional normalized width in the 0..1 range.'),
+                height: numberProperty('Optional normalized height in the 0..1 range.'),
+                text: stringProperty('Optional marker text or note.'),
+            },
+            required: ['sessionId', 'type', 'x', 'y'],
+        },
+    }));
+    register('bulk_add_annotated_attachment_markers', (context) => ({
+        description: context.describeTool('Add multiple markers to one annotation session in a single request. Useful for batch import after a first-pass review.'),
+        inputSchema: {
+            properties: {
+                sessionId: stringProperty('Annotated attachment session id.'),
+                markers: arrayProperty('Marker definitions to add.', {
+                    type: 'object',
+                    properties: {
+                        type: { type: 'string' },
+                        x: { type: 'number' },
+                        y: { type: 'number' },
+                        width: { type: 'number' },
+                        height: { type: 'number' },
+                        text: { type: 'string' },
+                    },
+                    required: ['type', 'x', 'y'],
+                }),
+            },
+            required: ['sessionId', 'markers'],
+        },
+    }));
+    register('update_annotated_attachment_marker', (context) => ({
+        description: context.describeTool('Update one existing annotation marker without recreating it.'),
+        inputSchema: {
+            properties: {
+                sessionId: stringProperty('Annotated attachment session id.'),
+                markerId: stringProperty('Marker id within the session.'),
+                type: stringProperty('Updated marker type.'),
+                x: numberProperty('Updated normalized x coordinate.'),
+                y: numberProperty('Updated normalized y coordinate.'),
+                width: numberProperty('Updated normalized width.'),
+                height: numberProperty('Updated normalized height.'),
+                text: stringProperty('Updated marker text.'),
+            },
+            required: ['sessionId', 'markerId'],
+        },
+    }));
+    register('reorder_annotated_attachment_marker', (context) => ({
+        description: context.describeTool('Move one marker within the session review order.'),
+        inputSchema: {
+            properties: {
+                sessionId: stringProperty('Annotated attachment session id.'),
+                markerId: stringProperty('Marker id within the session.'),
+                order: numberProperty('Target zero-based review order.'),
+            },
+            required: ['sessionId', 'markerId', 'order'],
+        },
+    }));
+    register('delete_annotated_attachment_marker', (context) => ({
+        description: context.describeTool('Delete one marker from an annotation session.'),
+        inputSchema: {
+            properties: {
+                sessionId: stringProperty('Annotated attachment session id.'),
+                markerId: stringProperty('Marker id within the session.'),
+            },
+            required: ['sessionId', 'markerId'],
+        },
+    }));
+    register('get_document_review_sessions', (context) => ({
+        description: context.describeTool('List review sessions for one document such as D-123. Use read_document_content first when you need to inspect the document body before choosing a session.'),
+        inputSchema: {
+            properties: {
+                documentId: stringProperty('Document asset id or document reference such as D-123.'),
+            },
+            required: ['documentId'],
+        },
+    }));
+    register('get_document_review_session', (context) => ({
+        description: context.describeTool('Get one document review session with its comments and summary state.'),
+        inputSchema: {
+            properties: {
+                sessionId: stringProperty('Document review session id.'),
+            },
+            required: ['sessionId'],
+        },
+    }));
+    register('create_document_review_session', (context) => ({
+        description: context.describeTool('Create a new document review session. Requires AI identity via resolve_profile before write operations.'),
+        inputSchema: {
+            properties: {
+                documentId: stringProperty('Document asset id or document reference such as D-123.'),
+                title: stringProperty('Optional review session title.'),
+            },
+            required: ['documentId'],
+        },
+    }));
+    register('update_document_review_session', (context) => ({
+        description: context.describeTool('Update a document review session title, status, or summary fields without creating a new session. Requires AI identity via resolve_profile before write operations.'),
+        inputSchema: {
+            properties: {
+                sessionId: stringProperty('Document review session id.'),
+                title: stringProperty('Updated review session title.'),
+                status: stringProperty('Updated review status.'),
+                summary: stringProperty('Updated review summary.'),
+            },
+            required: ['sessionId'],
+        },
+    }));
+    register('review_document', (context) => ({
+        description: context.describeTool('Run the lower-friction document review path for one document. This helper creates or updates the review workflow while preserving a lower-friction document review path than manual session management. Requires AI identity via resolve_profile before write operations.'),
+        inputSchema: {
+            properties: {
+                documentId: stringProperty('Document asset id or document reference such as D-123.'),
+                prompt: stringProperty('Review instructions or focus areas.'),
+            },
+            required: ['documentId', 'prompt'],
+        },
+    }));
+    register('add_document_review_comment', (context) => ({
+        description: context.describeTool('Add a comment to a document review session. Use this for review feedback that should stay attached to the document rather than the task. Requires AI identity via resolve_profile before write operations.'),
+        inputSchema: {
+            properties: {
+                sessionId: stringProperty('Document review session id.'),
+                body: stringProperty('Comment text.'),
+                anchor: { type: 'object', description: 'Optional anchor object such as a quote or line-range reference.' },
+            },
+            required: ['sessionId', 'body'],
+        },
+    }));
+    register('update_document_review_comment', (context) => ({
+        description: context.describeTool('Update an existing document review comment without creating a new comment.'),
+        inputSchema: {
+            properties: {
+                commentId: stringProperty('Document review comment id.'),
+                body: stringProperty('Updated comment text.'),
+            },
+            required: ['commentId', 'body'],
+        },
+    }));
+    register('delete_document_review_comment', (context) => ({
+        description: context.describeTool('Delete an existing document review comment when it should be removed entirely.'),
+        inputSchema: {
+            properties: {
+                commentId: stringProperty('Document review comment id.'),
+            },
+            required: ['commentId'],
+        },
+    }));
+    register('link_task_context', (context) => ({
+        description: context.describeTool('Attach an external http(s) URL as task context. link_task_context only supports an external http(s) URL; use save_task_attachment for files or generated content.'),
+        inputSchema: {
+            properties: {
+                id: stringProperty('Task ID or task reference such as T-123.'),
+                path: stringProperty('External http(s) URL to attach.'),
+                caption: stringProperty('Optional caption for the linked context entry.'),
+            },
+            required: ['id', 'path'],
+        },
+    }));
+    register('save_task_attachment', (context) => ({
+        description: context.describeTool('Save a file and attach it to a task. Use this for generated content or existing files from disk. Set overwrite=true to replace an existing canonical attachment with the same filename. For AI-authored markdown/text, use inline content for AI-authored markdown/text rather than writing an external temp file first.'),
+        inputSchema: {
+            properties: {
+                id: stringProperty('Task ID or task reference such as T-123.'),
+                filename: stringProperty('Destination filename for the attachment.'),
+                content: stringProperty('Inline file content; use this for AI-authored markdown/text attachments.'),
+                sourcePath: stringProperty('Path to an existing source file. Must be within project root, a Taskforce-managed attachment source, or an approved agent workspace root.'),
+                caption: stringProperty('Optional attachment caption.'),
+                overwrite: booleanProperty('When true, overwrite an existing canonical task attachment with the same filename instead of creating a new one.'),
+            },
+            required: ['id', 'filename'],
+        },
+    }));
+    register('delete_task_attachment', (context) => ({
+        description: context.describeTool('Delete one task attachment. Use get_task_attachments first to inspect attachment ids before removing one.'),
+        inputSchema: {
+            properties: {
+                taskId: stringProperty('Task ID or task reference such as T-123.'),
+                attachmentId: stringProperty('Attachment descriptor id from get_task_attachments.'),
+            },
+            required: ['taskId', 'attachmentId'],
+        },
+    }));
+}

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,
+    };
+}