@taskforcehq/taskforce 0.3.302 → 0.3.304

package/dist/mcp/runtime.test.js

@@ -1,4 +1,4 @@
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
@@ -7,61 +7,8 @@ import { MCP_TOOL_REGISTRY } from './toolRegistry';
 import { TaskforceCore, TaskforceRuleError } from '../core/Taskforce';
 import { WorkspaceAssetStore } from '../storage/workspaceAssetStore';
 import { ANNOTATED_ATTACHMENTS_WORKSPACE_FEATURE_KEY, APP_GATE_DEFINITIONS, } from '../runtime/appGates';
-function createProjectRoot() {
-    const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-mcp-runtime-'));
-    const core = new TaskforceCore({
-        projectRoot,
-        storagePath: path.join(projectRoot, '.taskforce')
-    });
-    try {
-        Object.defineProperty(core, 'getAccountAccessStatus', {
-            configurable: true,
-            value: () => ({
-                gate: 'ok',
-                hasEntitlement: true,
-                canAccessApp: true,
-                canAccessPlans: true,
-                signupMonetizationStrategy: 'none',
-                planSelectionRequired: false,
-                message: null,
-                entitlement: null
-            })
-        });
-        core.createWorkspace({ workspaceId: 'workspace-1', name: 'Workspace 1' });
-        core.ensureBootstrapUserAccess({
-            userId: 'owner-1',
-            workspaceId: 'workspace-1',
-            role: 'owner',
-            email: 'owner-1@example.com'
-        });
-    }
-    finally {
-        core.close();
-    }
-    return projectRoot;
-}
-async function listTools(projectRoot, runtimeMode) {
-    const runtime = createTaskforceMcpServer({
-        projectRoot,
-        runtimeMode,
-        logStartup: false,
-        auth: runtimeMode === 'cloud'
-            ? { scopes: ['tasks:read', 'tasks:write', 'workspace:read'] }
-            : undefined
-    });
-    const handler = runtime.server._requestHandlers.get('tools/list');
-    if (!handler) {
-        throw new Error('tools/list handler not registered');
-    }
-    return await handler({
-        jsonrpc: '2.0',
-        id: 'test-tools-list',
-        method: 'tools/list',
-        params: {}
-    }, {});
-}
-async function callTool(projectRoot, runtimeMode, name, args, options) {
-    const runtime = createTaskforceMcpServer({
+function createRuntime(projectRoot, runtimeMode, options) {
+    return createTaskforceMcpServer({
         projectRoot,
         runtimeMode,
         workspaceId: options?.workspaceId,
@@ -83,6 +30,8 @@ async function callTool(projectRoot, runtimeMode, name, args, options) {
             }
             : undefined
     });
+}
+async function callToolWithRuntime(runtime, name, args, options) {
     const handler = runtime.server._requestHandlers.get('tools/call');
     if (!handler) {
         throw new Error('tools/call handler not registered');
@@ -112,20 +61,71 @@ async function callTool(projectRoot, runtimeMode, name, args, options) {
         }
     }, {});
 }
-async function readResource(projectRoot, runtimeMode, uri, options) {
-    const runtime = createTaskforceMcpServer({
+async function subscribeResource(runtime, uri) {
+    const handler = runtime.server._requestHandlers.get('resources/subscribe');
+    if (!handler) {
+        throw new Error('resources/subscribe handler not registered');
+    }
+    await handler({
+        jsonrpc: '2.0',
+        id: `test-resources-subscribe-${uri}`,
+        method: 'resources/subscribe',
+        params: { uri }
+    }, {});
+}
+function createProjectRoot() {
+    const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-mcp-runtime-'));
+    const core = new TaskforceCore({
         projectRoot,
-        runtimeMode,
-        workspaceId: options?.workspaceId,
-        logStartup: false,
-        auth: runtimeMode === 'cloud'
-            ? {
-                scopes: ['tasks:read', 'tasks:write', 'workspace:read'],
-                userId: options?.authUserId || 'owner-1',
-                actorType: 'oauth'
-            }
-            : undefined
+        storagePath: path.join(projectRoot, '.taskforce')
+    });
+    try {
+        Object.defineProperty(core, 'getAccountAccessStatus', {
+            configurable: true,
+            value: () => ({
+                gate: 'ok',
+                hasEntitlement: true,
+                canAccessApp: true,
+                canAccessPlans: true,
+                planSelectionRequired: false,
+                message: null,
+                entitlement: null
+            })
+        });
+        core.createWorkspace({ workspaceId: 'workspace-1', name: 'Workspace 1' });
+        core.ensureBootstrapUserAccess({
+            userId: 'owner-1',
+            workspaceId: 'workspace-1',
+            role: 'owner',
+            email: 'owner-1@example.com'
+        });
+    }
+    finally {
+        core.close();
+    }
+    return projectRoot;
+}
+async function listTools(projectRoot, runtimeMode) {
+    const runtime = createRuntime(projectRoot, runtimeMode);
+    const handler = runtime.server._requestHandlers.get('tools/list');
+    if (!handler) {
+        throw new Error('tools/list handler not registered');
+    }
+    return await handler({
+        jsonrpc: '2.0',
+        id: 'test-tools-list',
+        method: 'tools/list',
+        params: {}
+    }, {});
+}
+async function callTool(projectRoot, runtimeMode, name, args, options) {
+    const runtime = createRuntime(projectRoot, runtimeMode, options);
+    return await callToolWithRuntime(runtime, name, args, {
+        resolveProfile: options?.resolveProfile,
     });
+}
+async function readResource(projectRoot, runtimeMode, uri, options) {
+    const runtime = createRuntime(projectRoot, runtimeMode, options);
     const handler = runtime.server._requestHandlers.get('resources/read');
     if (!handler) {
         throw new Error('resources/read handler not registered');
@@ -138,19 +138,7 @@ async function readResource(projectRoot, runtimeMode, uri, options) {
     }, {});
 }
 async function listResources(projectRoot, runtimeMode, options) {
-    const runtime = createTaskforceMcpServer({
-        projectRoot,
-        runtimeMode,
-        workspaceId: options?.workspaceId,
-        logStartup: false,
-        auth: runtimeMode === 'cloud'
-            ? {
-                scopes: ['tasks:read', 'tasks:write', 'workspace:read'],
-                userId: options?.authUserId || 'owner-1',
-                actorType: 'oauth'
-            }
-            : undefined
-    });
+    const runtime = createRuntime(projectRoot, runtimeMode, options);
     const handler = runtime.server._requestHandlers.get('resources/list');
     if (!handler) {
         throw new Error('resources/list handler not registered');
@@ -304,6 +292,29 @@ describe('Taskforce MCP tool descriptions', () => {
             fs.rmSync(projectRoot, { recursive: true, force: true });
         }
     });
+    it('does not let TASKFORCE_TOOLS prune the runtime tool catalog', async () => {
+        const projectRoot = createProjectRoot();
+        const previousValue = process.env.TASKFORCE_TOOLS;
+        process.env.TASKFORCE_TOOLS = 'get_task';
+        try {
+            const result = await listTools(projectRoot, 'cloud');
+            const runtimeToolNames = result.tools.map((tool) => tool.name).sort();
+            const registryToolNames = Object.entries(MCP_TOOL_REGISTRY)
+                .filter(([, entry]) => entry.permission.kind !== 'local-only' && entry.permission.kind !== 'session-only')
+                .map(([name]) => name)
+                .sort();
+            expect(runtimeToolNames).toEqual(registryToolNames);
+        }
+        finally {
+            if (previousValue === undefined) {
+                delete process.env.TASKFORCE_TOOLS;
+            }
+            else {
+                process.env.TASKFORCE_TOOLS = previousValue;
+            }
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
     it('includes local-only guidance in local runtime tool descriptions', async () => {
         const projectRoot = createProjectRoot();
         try {
@@ -425,11 +436,11 @@ describe('Taskforce MCP tool descriptions', () => {
             expect(linkTaskContext.description).toContain('external http(s) URL');
             expect(saveTaskAttachment.description).toContain('generated content');
             expect(saveTaskAttachment.description).toContain('overwrite=true');
-            expect(saveTaskAttachment.description).toContain('AI-authored markdown/text should usually be passed inline via content');
+            expect(saveTaskAttachment.description).toContain('use inline content for AI-authored markdown/text');
             expect(saveTaskAttachment.inputSchema).toBeDefined();
             const saveTaskAttachmentSchema = saveTaskAttachment.inputSchema;
             expect(saveTaskAttachmentSchema.properties.content.description).toContain('use this for AI-authored markdown/text attachments');
-            expect(saveTaskAttachmentSchema.properties.sourcePath.description).toContain('local runtime only today');
+            expect(saveTaskAttachmentSchema.properties.sourcePath.description).toContain('approved agent workspace root');
             expect(resolveProfile.description).toContain('AI collaborator profile');
             expect(resolveProfile.description).toContain('Update semantics');
             expect(resolveProfile.description).toContain('empty strings are ignored rather than clearing');
@@ -1500,6 +1511,150 @@ describe('Taskforce MCP tool descriptions', () => {
             fs.rmSync(projectRoot, { recursive: true, force: true });
         }
     });
+    it('builds workstream listings from one historical task snapshot and returns task summaries', async () => {
+        const projectRoot = createProjectRoot();
+        const core = new TaskforceCore({
+            projectRoot,
+            storagePath: path.join(projectRoot, '.taskforce')
+        });
+        try {
+            const category = core.getCategories()[0]?.value;
+            const type = core.getTypes()[0]?.value;
+            const firstWorkstream = core.createWorkstream({ title: 'Workstream one' }, 'workspace-1');
+            const secondWorkstream = core.createWorkstream({ title: 'Workstream two' }, 'workspace-1');
+            core.createTask({
+                title: 'Linked task one',
+                category,
+                type,
+                workstreamId: firstWorkstream.id,
+            }, { workspaceId: 'workspace-1', actorRef: 'owner-1' });
+            core.createTask({
+                title: 'Linked task two',
+                category,
+                type,
+                workstreamId: secondWorkstream.id,
+            }, { workspaceId: 'workspace-1', actorRef: 'owner-1' });
+            const archivedTask = core.createTask({
+                title: 'Archived linked task',
+                category,
+                type,
+                workstreamId: firstWorkstream.id,
+                status: 'done',
+            }, { workspaceId: 'workspace-1', actorRef: 'owner-1' });
+            core.archiveTask(archivedTask.id, false, undefined, 'workspace-1', { actorRef: 'owner-1' });
+        }
+        finally {
+            core.close();
+        }
+        const listTasksSpy = vi.spyOn(TaskforceCore.prototype, 'listTasks');
+        const listArchiveSpy = vi.spyOn(TaskforceCore.prototype, 'listArchive');
+        try {
+            const beforeListTasksCalls = listTasksSpy.mock.calls.length;
+            const beforeListArchiveCalls = listArchiveSpy.mock.calls.length;
+            const payload = parseToolJson(await callTool(projectRoot, 'local', 'list_workstreams', {}));
+            const firstWorkstreamPayload = payload.workstreams.find((entry) => entry.workstream.title === 'Workstream one');
+            const linkedTask = firstWorkstreamPayload?.tasks.find((task) => task.title === 'Archived linked task');
+            expect(listTasksSpy.mock.calls.length - beforeListTasksCalls).toBe(1);
+            expect(listArchiveSpy.mock.calls.length - beforeListArchiveCalls).toBe(1);
+            expect(linkedTask).toMatchObject({
+                title: 'Archived linked task',
+                workstreamId: firstWorkstreamPayload?.workstream.id,
+                status: 'done',
+            });
+            expect(linkedTask.description).toBeUndefined();
+            expect(linkedTask.comments).toBeUndefined();
+            expect(linkedTask.activity).toBeUndefined();
+            expect(linkedTask.attachments).toBeUndefined();
+            expect(linkedTask.checklistItems).toBeUndefined();
+        }
+        finally {
+            listTasksSpy.mockRestore();
+            listArchiveSpy.mockRestore();
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('queues bulk resource invalidations instead of awaiting them in the write path', async () => {
+        const projectRoot = createProjectRoot();
+        const runtime = createRuntime(projectRoot, 'local');
+        const resourceUri = `taskforce://${path.basename(projectRoot)}/tasks`;
+        const sendResourceUpdatedSpy = vi
+            .spyOn(runtime.server, 'sendResourceUpdated')
+            .mockImplementation(async () => {
+            await new Promise((resolve) => setTimeout(resolve, 25));
+        });
+        try {
+            await subscribeResource(runtime, resourceUri);
+            const created = parseToolJson(await callToolWithRuntime(runtime, 'create_task', {
+                title: 'Queued invalidation task'
+            }));
+            expect(created.title).toBe('Queued invalidation task');
+            expect(sendResourceUpdatedSpy).not.toHaveBeenCalled();
+            await new Promise((resolve) => setTimeout(resolve, 40));
+            expect(sendResourceUpdatedSpy).toHaveBeenCalledTimes(1);
+            expect(sendResourceUpdatedSpy).toHaveBeenCalledWith({ uri: resourceUri });
+        }
+        finally {
+            sendResourceUpdatedSpy.mockRestore();
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('reads the bulk tasks resource as summary-only rows', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const created = parseToolJson(await callTool(projectRoot, 'local', 'create_task', {
+                title: 'Verbose task',
+                description: 'This should stay off the bulk tasks resource'
+            }));
+            await callTool(projectRoot, 'local', 'add_comment', {
+                id: created.referenceLabel,
+                text: 'This comment should stay off the bulk tasks resource',
+                author: 'ai-profile-019d15c5-6ad3-7bf0-9b9e-fa9c366c3ff4'
+            });
+            const taskResource = await readResource(projectRoot, 'cloud', `taskforce://${path.basename(projectRoot)}/tasks`, {
+                workspaceId: 'workspace-1',
+                authUserId: 'owner-1'
+            });
+            const payload = JSON.parse(String(taskResource.contents[0]?.text || '{}'));
+            const resourceTask = payload.tasks.find((task) => task.referenceLabel === created.referenceLabel);
+            expect(resourceTask).toMatchObject({
+                referenceLabel: created.referenceLabel,
+                title: 'Verbose task',
+            });
+            expect(resourceTask.description).toBeUndefined();
+            expect(resourceTask.comments).toBeUndefined();
+            expect(resourceTask.activity).toBeUndefined();
+            expect(resourceTask.attachments).toBeUndefined();
+            expect(resourceTask.checklistItems).toBeUndefined();
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('reads initiative listings with summary initiative and workstream records only', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const initiative = parseToolJson(await callTool(projectRoot, 'local', 'create_initiative', {
+                title: 'Summary initiative',
+                description: 'Verbose initiative details should stay off the bulk listing'
+            }));
+            await callTool(projectRoot, 'local', 'create_workstream', {
+                title: 'Summary workstream',
+                description: 'Verbose workstream details should stay off the bulk listing',
+                initiativeId: initiative.initiative.referenceLabel
+            });
+            const initiatives = parseToolJson(await callTool(projectRoot, 'local', 'list_initiatives', {}));
+            const listedInitiative = initiatives.initiatives.find((entry) => entry.initiative.referenceLabel === initiative.initiative.referenceLabel);
+            const listedWorkstream = listedInitiative?.workstreams.find((entry) => entry.title === 'Summary workstream');
+            expect(listedInitiative).toBeTruthy();
+            expect(listedInitiative.initiative.description).toBeUndefined();
+            expect(listedWorkstream).toBeTruthy();
+            expect(listedWorkstream.description).toBeUndefined();
+            expect(listedWorkstream.taskIds).toBeUndefined();
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
     it('creates MCP tasks as unassigned when no explicit assignee is provided', async () => {
         const projectRoot = createProjectRoot();
         try {
@@ -1512,6 +1667,40 @@ describe('Taskforce MCP tool descriptions', () => {
             fs.rmSync(projectRoot, { recursive: true, force: true });
         }
     });
+    it('returns summary-only rows from list_tasks json output', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const created = parseToolJson(await callTool(projectRoot, 'local', 'create_task', {
+                title: 'List summary task',
+                description: 'Verbose description that should not appear in list rows'
+            }));
+            await callTool(projectRoot, 'local', 'replace_task_checklist', {
+                taskId: created.referenceLabel,
+                items: [
+                    { title: 'Checklist item one', isCompleted: false }
+                ]
+            });
+            await callTool(projectRoot, 'local', 'add_comment', {
+                id: created.referenceLabel,
+                text: 'Verbose comment that should not appear in list rows',
+                author: 'ai-profile-019d15c5-6ad3-7bf0-9b9e-fa9c366c3ff4'
+            });
+            const listed = parseToolJson(await callTool(projectRoot, 'local', 'list_tasks', {
+                format: 'json'
+            }));
+            const row = listed.find((task) => task.referenceLabel === created.referenceLabel);
+            expect(row).toBeTruthy();
+            expect(row.description).toBeUndefined();
+            expect(row.comments).toBeUndefined();
+            expect(row.taskEvents).toBeUndefined();
+            expect(row.activity).toBeUndefined();
+            expect(row.attachments).toBeUndefined();
+            expect(row.checklistItems).toBeUndefined();
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
     it('reads task resources by T-XXX reference and exposes version/scope in config resource', async () => {
         const projectRoot = createProjectRoot();
         try {
@@ -1541,6 +1730,42 @@ describe('Taskforce MCP tool descriptions', () => {
             fs.rmSync(projectRoot, { recursive: true, force: true });
         }
     });
+    it('returns summary-shaped task entries from the shared tasks resource', async () => {
+        const projectRoot = createProjectRoot();
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            core.createTask({
+                title: 'Resource summary task',
+                description: 'Verbose task description',
+                comments: [{ id: 'comment-1', author: 'user', text: 'Hello', timestamp: '2026-04-13T01:00:00.000Z' }],
+                attachments: [{ name: 'note.md', path: 'notes/note.md' }],
+                checklistItems: [{ id: 'item-1', taskId: 'temp', title: 'Check me', isCompleted: false, order: 0, createdAt: '2026-04-13T01:00:00.000Z' }],
+            }, {
+                workspaceId: 'workspace-1',
+                actorRef: 'owner-1'
+            });
+            core.close();
+            const tasksResource = await readResource(projectRoot, 'cloud', `taskforce://${path.basename(projectRoot)}/tasks`, {
+                workspaceId: 'workspace-1',
+                authUserId: 'owner-1'
+            });
+            const payload = JSON.parse(String(tasksResource.contents[0]?.text || '{}'));
+            const task = payload.tasks.find((entry) => entry.title === 'Resource summary task');
+            expect(task).toBeDefined();
+            expect(task.description).toBeUndefined();
+            expect(task.comments).toBeUndefined();
+            expect(task.taskEvents).toBeUndefined();
+            expect(task.activity).toBeUndefined();
+            expect(task.attachments).toBeUndefined();
+            expect(task.checklistItems).toBeUndefined();
+        }
+        finally {
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
     it('persists save_task_attachment through canonical task attachments', async () => {
         const projectRoot = createProjectRoot();
         try {
@@ -1770,8 +1995,45 @@ describe('Taskforce MCP tool descriptions', () => {
             fs.rmSync(projectRoot, { recursive: true, force: true });
         }
     });
-    it('rejects sourcePath for save_task_attachment in cloud runtime', async () => {
+    it('allows save_task_attachment sourcePath in cloud runtime for approved agent workspace roots', async () => {
         const projectRoot = createProjectRoot();
+        const agentWorkspaceRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-mcp-agent-workspace-'));
+        const previousRoots = process.env.TASKFORCE_ALLOWED_ATTACHMENT_SOURCE_ROOTS;
+        try {
+            const core = new TaskforceCore({
+                projectRoot,
+                storagePath: path.join(projectRoot, '.taskforce')
+            });
+            const task = core.createTask({ title: 'Cloud sourcePath allow test' }, { workspaceId: 'workspace-1' });
+            core.close();
+            const sourcePath = path.join(agentWorkspaceRoot, 'implementation-plan.md');
+            fs.writeFileSync(sourcePath, '# Recovered implementation plan', 'utf8');
+            process.env.TASKFORCE_ALLOWED_ATTACHMENT_SOURCE_ROOTS = agentWorkspaceRoot;
+            await callTool(projectRoot, 'cloud', 'save_task_attachment', {
+                id: task.id,
+                filename: 'implementation-plan.md',
+                sourcePath
+            });
+            const readBack = parseToolJson(await callTool(projectRoot, 'cloud', 'read_task_attachment', {
+                taskId: task.id,
+                attachmentId: parseToolJson(await callTool(projectRoot, 'cloud', 'get_task_attachments', { id: task.id })).attachments[0]?.attachmentId
+            }));
+            expect(readBack.content).toContain('# Recovered implementation plan');
+        }
+        finally {
+            if (previousRoots === undefined) {
+                delete process.env.TASKFORCE_ALLOWED_ATTACHMENT_SOURCE_ROOTS;
+            }
+            else {
+                process.env.TASKFORCE_ALLOWED_ATTACHMENT_SOURCE_ROOTS = previousRoots;
+            }
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+            fs.rmSync(agentWorkspaceRoot, { recursive: true, force: true });
+        }
+    });
+    it('rejects save_task_attachment sourcePath in cloud runtime for unapproved roots', async () => {
+        const projectRoot = createProjectRoot();
+        const externalRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-mcp-cloud-unapproved-'));
         try {
             const core = new TaskforceCore({
                 projectRoot,
@@ -1779,16 +2041,18 @@ describe('Taskforce MCP tool descriptions', () => {
             });
             const task = core.createTask({ title: 'Cloud sourcePath reject test' }, { workspaceId: 'workspace-1' });
             core.close();
+            const sourcePath = path.join(externalRoot, 'outside.md');
+            fs.writeFileSync(sourcePath, '# Outside approved roots', 'utf8');
             const result = await callTool(projectRoot, 'cloud', 'save_task_attachment', {
                 id: task.id,
-                filename: 'copy.txt',
-                sourcePath: 'docs/source.txt'
+                filename: 'outside.md',
+                sourcePath
             });
-            expect(result.content?.[0]?.text).toContain('does not support sourcePath for save_task_attachment yet');
-            expect(result.content?.[0]?.text).toContain('resend the attachment using inline content instead');
+            expect(result.content?.[0]?.text).toContain('sourcePath must be within project root, a Taskforce-managed attachment source, or an approved agent workspace root');
         }
         finally {
             fs.rmSync(projectRoot, { recursive: true, force: true });
+            fs.rmSync(externalRoot, { recursive: true, force: true });
         }
     });
     it('accepts task references for save_task_attachment', async () => {
@@ -2140,7 +2404,7 @@ describe('Taskforce MCP tool descriptions', () => {
                 filename: 'outside.md',
                 sourcePath: externalSourcePath
             });
-            expect(result.content?.[0]?.text).toContain('sourcePath must be within project root or a Taskforce-managed attachment source');
+            expect(result.content?.[0]?.text).toContain('sourcePath must be within project root, a Taskforce-managed attachment source, or an approved agent workspace root');
         }
         finally {
             fs.rmSync(projectRoot, { recursive: true, force: true });

package/dist/mcp/taskAttachmentHelpers.d.ts

@@ -0,0 +1,41 @@
+import type { WorkspaceAssetEntry, WorkspaceAssetKind, WorkspaceAssetStore } from '../storage/workspaceAssetStore.js';
+import type { McpTaskAttachmentDescriptor, TaskAttachmentRecord } from './taskAttachmentTypes.js';
+export interface TaskAttachmentHelpersDeps {
+    activeWorkspaceId: string;
+    workspaceAssetStore: WorkspaceAssetStore | null;
+    getImageReferenceLabel: (asset: WorkspaceAssetEntry | null | undefined) => string | null;
+    getDocumentReferenceLabel: (asset: WorkspaceAssetEntry | null | undefined) => string | null;
+    inferMimeTypeFromPath: (filePath: string) => string;
+    inferAssetKind: (filePath: string, mimeType: string) => WorkspaceAssetKind;
+    isTextReadableMimeType: (mimeTypeRaw: string) => boolean;
+    isValidCanonicalDocumentAsset: (params: Pick<WorkspaceAssetEntry, 'kind' | 'storageKey' | 'originalFilename' | 'mimeType'>) => boolean;
+    canonicalAssetHelpers: {
+        getAttachmentAssetRecord: (attachment: TaskAttachmentRecord) => WorkspaceAssetEntry | null;
+        normalizeAttachmentStorageKey: (pathValue: unknown, fsPathValue: unknown) => string | null;
+        buildSyntheticAttachmentId: (taskId: string, attachment: TaskAttachmentRecord) => string;
+        toTaskAttachmentRecord: (attachment: string | TaskAttachmentRecord) => TaskAttachmentRecord;
+    };
+    documentHelpers: {
+        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;
+    };
+}
+export declare function createTaskAttachmentHelpers(deps: TaskAttachmentHelpersDeps): {
+    describeTaskAttachment: (taskId: string, attachmentInput: string | TaskAttachmentRecord) => McpTaskAttachmentDescriptor;
+    listTaskAttachmentDescriptors: (task: {
+        id: string;
+        attachments?: Array<string | TaskAttachmentRecord> | null;
+    }) => McpTaskAttachmentDescriptor[];
+};

package/dist/mcp/taskAttachmentHelpers.js

@@ -0,0 +1,60 @@
+export function createTaskAttachmentHelpers(deps) {
+    const isCanonicalDocumentAssetRecord = (asset) => deps.isValidCanonicalDocumentAsset(asset);
+    const describeTaskAttachment = (taskId, attachmentInput) => {
+        const attachment = deps.canonicalAssetHelpers.toTaskAttachmentRecord(attachmentInput);
+        const asset = deps.canonicalAssetHelpers.getAttachmentAssetRecord(attachment);
+        const storageKey = deps.canonicalAssetHelpers.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) ? deps.inferMimeTypeFromPath(storageKey) : '')
+            || deps.inferMimeTypeFromPath(String(attachment.originalFilename || attachment.displayName || attachment.caption || attachment.path || ''))).trim() || 'application/octet-stream';
+        const kind = asset?.kind || deps.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' ? deps.getImageReferenceLabel(asset) : '')
+            || (isCanonicalDocument ? deps.getDocumentReferenceLabel(asset) : '')).trim() || null;
+        const readableAsText = source === 'canonical' && deps.isTextReadableMimeType(mimeType);
+        const canonicalDocumentHint = isCanonicalDocument && source === 'canonical' && asset
+            ? deps.documentHelpers.buildCanonicalDocumentAttachmentHint(asset)
+            : null;
+        return {
+            attachmentId: assetId || deps.canonicalAssetHelpers.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));
+    };
+    return {
+        describeTaskAttachment,
+        listTaskAttachmentDescriptors,
+    };
+}