@taskforcehq/taskforce 0.3.326 → 0.3.328

package/dist/mcp/taskAttachmentCommandAdapter.d.ts

@@ -0,0 +1,192 @@
+import type { createCanonicalAssetHelpers } from './canonicalAssetHelpers.js';
+import type { createTaskAttachmentHelpers } from './taskAttachmentHelpers.js';
+import type { TaskAttachmentRecord } from './taskAttachmentTypes.js';
+import type { WorkspaceAssetEntry, WorkspaceAssetKind, WorkspaceAssetScanStatus, WorkspaceAssetStore } from '../storage/workspaceAssetStore.js';
+type CanonicalAssetHelpers = ReturnType<typeof createCanonicalAssetHelpers>;
+type TaskAttachmentHelpers = ReturnType<typeof createTaskAttachmentHelpers>;
+interface TaskAttachmentTask {
+    id: string;
+    attachments?: Array<string | TaskAttachmentRecord> | null;
+    [key: string]: unknown;
+}
+interface TaskAttachmentUploadDraft {
+    draftId: string;
+    workspaceId: string;
+    taskId: string;
+    actorRef: string;
+    storageKey: string;
+    mimeType: string;
+    originalFilename: string;
+    sizeBytes: number;
+    createdAt: string;
+    discardedAt?: string | null;
+    consumedAt?: string | null;
+}
+interface ObjectStorageAdapter {
+    createSignedPutUrl(storageKey: string, expiresInSeconds: number, contentType: string): string;
+    getObject(storageKey: string): Promise<{
+        body: Buffer;
+        contentType?: string | null;
+    } | null>;
+    deleteObject(storageKey: string): Promise<unknown>;
+}
+interface AttachmentScanResult {
+    verdict?: string;
+    engine?: string | null;
+    details?: string | null;
+    failClosed?: boolean;
+}
+interface IntegrityResult {
+    sizeBytes: number;
+    sha256: string;
+    verified?: true;
+}
+export interface SaveTaskAttachmentInput {
+    id?: unknown;
+    filename?: unknown;
+    content?: unknown;
+    sourcePath?: unknown;
+    uploadedPath?: unknown;
+    uploadDraftId?: unknown;
+    mimeType?: unknown;
+    sizeBytes?: unknown;
+    expectedSizeBytes?: unknown;
+    expectedSha256?: unknown;
+    displayName?: unknown;
+    caption?: unknown;
+    overwrite?: unknown;
+    overwriteAssetId?: unknown;
+}
+export type SaveTaskAttachmentResult = {
+    kind: 'staged-upload';
+    taskId: string;
+    task: TaskAttachmentTask;
+    inputId: unknown;
+    filename: string;
+    mimeType: string;
+    sizeBytes: number;
+    assetId: string;
+    uploadDraftId: string;
+    expiresAt: string;
+    uploadUrl: string;
+    uploadedPath: string;
+    displayName?: string;
+    caption?: string;
+    overwrite: boolean;
+    expectedSizeBytes?: unknown;
+    expectedSha256?: unknown;
+} | {
+    kind: 'saved';
+    outcome: 'attached' | 'duplicate' | 'overwritten';
+    taskId: string;
+    task: TaskAttachmentTask;
+    attachment: TaskAttachmentRecord;
+    asset: WorkspaceAssetEntry | null;
+    integrity: IntegrityResult | null;
+    storageKeyForAudit: string;
+    auditAttachmentId?: string;
+    unchanged?: boolean;
+    versionCreated?: boolean;
+};
+export interface DeleteTaskAttachmentResult {
+    taskId: string;
+    task: TaskAttachmentTask;
+    attachmentId: string;
+    canonicalAssetDeleted: boolean;
+    deletedAnnotatedSessions: number;
+}
+export interface TaskAttachmentCommandAdapterDependencies {
+    activeWorkspaceId: string;
+    runtimeMode: 'local' | 'cloud';
+    objectStorageClient: ObjectStorageAdapter | null;
+    objectStorageConfig: {
+        provider: string;
+        r2?: {
+            signedUploadTtlSeconds: number;
+        } | null;
+    };
+    workspaceAssetStore: WorkspaceAssetStore | null;
+    canonicalAssetHelpers: CanonicalAssetHelpers;
+    taskAttachmentHelpers: TaskAttachmentHelpers;
+    resolveTask(identifier: unknown): {
+        id: string;
+        task: TaskAttachmentTask;
+    };
+    durableAttachmentLinksEnabled(taskId: string): boolean;
+    replaceAttachments(taskId: string, attachments: Array<string | TaskAttachmentRecord>, operationKey: string): void;
+    getPaths(): {
+        projectRoot: string;
+        basePath: string;
+    };
+    getActorRef(): string;
+    stableRequestId(scope: 'operation', key: string): string | null;
+    createUploadDraft(input: {
+        draftId: string;
+        workspaceId: string;
+        taskId: string;
+        actorRef: string;
+        storageKey: string;
+        mimeType: string;
+        originalFilename: string;
+        sizeBytes: number;
+        storageProvider: 'r2';
+    }): unknown;
+    getUploadDraft(draftId: string): TaskAttachmentUploadDraft | null;
+    discardUploadDraft(draftId: string): unknown;
+    consumeUploadDraft(draftId: string): unknown;
+    deleteAnnotatedSessionsForImage(input: {
+        workspaceId: string;
+        imageAssetId: string;
+        deletedAt: string;
+    }): number;
+    publishContentVersion(input: {
+        asset: WorkspaceAssetEntry;
+        body: Buffer;
+        sourceUpdatedAt: string;
+    }): Promise<void>;
+    hasPublishedContentVersion?(asset: WorkspaceAssetEntry): boolean;
+    scanBuffer(body: Buffer): Promise<AttachmentScanResult>;
+    sanitizeFilename(value: unknown): string;
+    inferMimeType(filePath: string): string;
+    inferAssetKind(filePath: string, mimeType: string): WorkspaceAssetKind;
+    scanStatus(verdict: string | undefined): WorkspaceAssetScanStatus;
+    inferWorkspaceIdFromStoragePath(storagePath: string): string;
+    normalizeStoragePath(storagePath: string): string | null;
+    verifyIntegrity(body: Buffer, expectedSizeBytes: unknown, expectedSha256: unknown): IntegrityResult;
+    validateStructuredDocument(relativePath: string, content: string): {
+        ok: true;
+    } | {
+        ok: false;
+        message: string;
+    };
+    isApprovedSourcePath(filePath: string, projectRootReal: string): boolean;
+    resolveStoragePathInsideRoot(basePath: string, storageKey: unknown): string | null;
+    toPosixPath(filePath: string): string;
+    isValidCanonicalDocumentAsset(asset: WorkspaceAssetEntry): boolean;
+    getDocumentReferenceLabel(asset: WorkspaceAssetEntry): string | null;
+    createError(message: string, code?: string, statusCode?: number): Error;
+    now?(): Date;
+}
+export declare function createTaskAttachmentCommandAdapter(deps: TaskAttachmentCommandAdapterDependencies): {
+    buildAttachmentResponse: (attachment: TaskAttachmentRecord, asset: WorkspaceAssetEntry | null, integrity: IntegrityResult | null) => {
+        integrity: IntegrityResult | null;
+        version?: number | undefined;
+        referenceLabel?: string | null;
+        path: string;
+        fsPath?: string;
+        caption?: string;
+        displayName?: string;
+        originalFilename?: string;
+        timestamp?: string;
+        assetId?: string | null;
+        referenceNumber?: number | null;
+        taskId?: string | null;
+        linkRole?: import("../storage/workspaceAssetStore.js").WorkspaceAssetLinkRole;
+    };
+    save(input: SaveTaskAttachmentInput): Promise<SaveTaskAttachmentResult>;
+    delete(input: {
+        taskId: unknown;
+        attachmentId: unknown;
+    }): DeleteTaskAttachmentResult;
+};
+export {};

package/dist/mcp/taskAttachmentCommandAdapter.js

@@ -0,0 +1,470 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { createHash, randomUUID } from 'node:crypto';
+export function createTaskAttachmentCommandAdapter(deps) {
+    const nowDate = () => deps.now?.() ?? new Date();
+    const fail = (message, code, statusCode) => {
+        throw deps.createError(message, code, statusCode);
+    };
+    const buildAttachmentResponse = (attachment, asset, integrity) => {
+        const referenceLabel = asset?.kind === 'document' && deps.isValidCanonicalDocumentAsset(asset)
+            ? deps.getDocumentReferenceLabel(asset)
+            : null;
+        return {
+            ...attachment,
+            ...(referenceLabel ? { referenceLabel } : {}),
+            ...(referenceLabel && asset?.version != null ? { version: asset.version } : {}),
+            integrity,
+        };
+    };
+    return {
+        buildAttachmentResponse,
+        async save(input) {
+            const { id: inputId, filename, content, sourcePath, uploadedPath, uploadDraftId, mimeType, sizeBytes, expectedSizeBytes, expectedSha256, displayName, caption, overwrite = false, overwriteAssetId, } = input;
+            const { id, task } = deps.resolveTask(inputId);
+            const durableAttachmentLinksEnabled = deps.durableAttachmentLinksEnabled(id);
+            if (!filename || typeof filename !== 'string')
+                fail('filename is required');
+            const hasContent = typeof content === 'string';
+            const hasSourcePath = typeof sourcePath === 'string' && sourcePath.trim().length > 0;
+            const hasUploadedPath = typeof uploadedPath === 'string' && uploadedPath.trim().length > 0;
+            if (hasSourcePath && deps.runtimeMode === 'cloud') {
+                fail('sourcePath is only available in local runtimes. In cloud runtime, use content or the staged upload flow instead.');
+            }
+            const contentModeCount = Number(hasContent) + Number(hasSourcePath) + Number(hasUploadedPath);
+            const nowValue = nowDate();
+            const now = nowValue.toISOString();
+            const safeCaption = typeof caption === 'string' && caption.trim().length > 0
+                ? caption.trim()
+                : undefined;
+            const safeFilename = deps.sanitizeFilename(filename);
+            const safeDisplayName = typeof displayName === 'string' && displayName.trim().length > 0
+                ? displayName.trim()
+                : safeFilename;
+            const stableAttachmentAssetId = deps.stableRequestId('operation', `task-attachment-asset:${id}:${safeFilename}`)?.replace(/^operation-/, 'asset-') || `asset-${randomUUID().replace(/-/g, '')}`;
+            const safeMimeType = typeof mimeType === 'string' && mimeType.trim().length > 0
+                ? mimeType.trim().toLowerCase()
+                : '';
+            const numericSizeBytes = Number(sizeBytes);
+            const hasStagedInitMetadata = !!safeMimeType && Number.isFinite(numericSizeBytes) && numericSizeBytes > 0;
+            const { projectRoot, basePath } = deps.getPaths();
+            const overwriteTarget = overwrite === true
+                ? deps.canonicalAssetHelpers.resolveCanonicalOverwriteTarget(task, safeFilename, deps.taskAttachmentHelpers.describeTaskAttachment, overwriteAssetId)
+                : null;
+            const buildAttachmentRecord = (asset, storageKey) => {
+                const isMarkdownDocument = storageKey.toLowerCase().endsWith('.md') || storageKey.toLowerCase().endsWith('.markdown');
+                const overwriteTitle = overwriteTarget
+                    ? deps.workspaceAssetStore?.getDocument?.(overwriteTarget.asset.assetId, deps.activeWorkspaceId)?.title
+                    : null;
+                const canonicalName = safeCaption || overwriteTitle || overwriteTarget?.asset.logicalName || safeFilename;
+                const persistedCaption = isMarkdownDocument
+                    ? canonicalName
+                    : (safeCaption || overwriteTarget?.attachment.caption || safeFilename);
+                return {
+                    path: overwriteTarget?.attachment.path || (asset?.kind === 'document' && deps.isValidCanonicalDocumentAsset(asset) && asset.assetId
+                        ? `/api/taskforce/documents/${encodeURIComponent(asset.assetId)}/content`
+                        : `/api/taskforce/context/${encodeURIComponent(storageKey)}`),
+                    fsPath: asset?.storageKey || overwriteTarget?.attachment.fsPath || storageKey,
+                    caption: isMarkdownDocument ? canonicalName : persistedCaption,
+                    displayName: safeDisplayName,
+                    originalFilename: safeFilename,
+                    ...(asset?.assetId ? { assetId: asset.assetId } : {}),
+                    timestamp: now,
+                };
+            };
+            if (contentModeCount === 0) {
+                if (!hasStagedInitMetadata) {
+                    fail('Provide exactly one of: content, sourcePath, or uploadedPath. To start a staged remote upload, provide mimeType and sizeBytes.');
+                }
+                const objectStorageClient = deps.objectStorageClient;
+                const r2Config = deps.objectStorageConfig.r2;
+                if (deps.runtimeMode !== 'cloud' || !objectStorageClient || deps.objectStorageConfig.provider !== 'r2' || !r2Config) {
+                    fail('Staged remote uploads require cloud runtime with object storage enabled. Otherwise provide content or sourcePath.');
+                }
+                const stagedAsset = deps.canonicalAssetHelpers.buildCanonicalWorkspaceAssetRelativePath({
+                    workspaceIdRaw: deps.activeWorkspaceId,
+                    kind: deps.inferAssetKind(safeFilename, safeMimeType),
+                    filename: safeFilename,
+                });
+                const draftId = `task-attachment-draft-${randomUUID().replace(/-/g, '')}`;
+                const uploadExpiresInSeconds = Math.max(1, Math.floor(r2Config.signedUploadTtlSeconds));
+                const expiresAt = new Date(nowValue.getTime() + uploadExpiresInSeconds * 1000).toISOString();
+                deps.createUploadDraft({
+                    draftId,
+                    workspaceId: deps.activeWorkspaceId,
+                    taskId: id,
+                    actorRef: deps.getActorRef(),
+                    storageKey: stagedAsset.relativePath,
+                    mimeType: safeMimeType,
+                    originalFilename: safeFilename,
+                    sizeBytes: Math.floor(numericSizeBytes),
+                    storageProvider: 'r2',
+                });
+                return {
+                    kind: 'staged-upload',
+                    taskId: id,
+                    task,
+                    inputId,
+                    filename: safeFilename,
+                    mimeType: safeMimeType,
+                    sizeBytes: Math.floor(numericSizeBytes),
+                    assetId: stagedAsset.assetId,
+                    uploadDraftId: draftId,
+                    expiresAt,
+                    uploadUrl: objectStorageClient.createSignedPutUrl(stagedAsset.relativePath, uploadExpiresInSeconds, safeMimeType),
+                    uploadedPath: stagedAsset.relativePath,
+                    ...(safeDisplayName !== safeFilename ? { displayName: safeDisplayName } : {}),
+                    ...(safeCaption ? { caption: safeCaption } : {}),
+                    overwrite: overwrite === true,
+                    ...(expectedSizeBytes !== undefined ? { expectedSizeBytes } : {}),
+                    ...(expectedSha256 !== undefined ? { expectedSha256 } : {}),
+                };
+            }
+            if (contentModeCount > 1) {
+                fail('Provide exactly one of: content, sourcePath, or uploadedPath');
+            }
+            let attachment;
+            let asset = null;
+            let storageKeyForAudit = '';
+            let replacedStorageKey = null;
+            let consumedUploadDraftId = null;
+            let integrity = null;
+            let documentContentUnchanged = false;
+            let documentVersionCreated = false;
+            if (hasUploadedPath) {
+                if (!deps.objectStorageClient || deps.objectStorageConfig.provider !== 'r2') {
+                    fail('uploadedPath requires object storage to be enabled for this MCP runtime.');
+                }
+                if (!deps.workspaceAssetStore) {
+                    fail('uploadedPath requires canonical asset storage support.');
+                }
+                const objectStorageClient = deps.objectStorageClient;
+                const workspaceAssetStore = deps.workspaceAssetStore;
+                const normalizedUploadDraftId = typeof uploadDraftId === 'string' ? uploadDraftId.trim() : '';
+                if (!normalizedUploadDraftId) {
+                    fail('uploadedPath finalization requires uploadDraftId from the staged upload init response.');
+                }
+                const draft = deps.getUploadDraft(normalizedUploadDraftId);
+                if (!draft || draft.discardedAt || draft.consumedAt) {
+                    fail('uploadDraftId is invalid, expired, or already consumed.');
+                }
+                const validDraft = draft;
+                if (validDraft.workspaceId !== deps.activeWorkspaceId) {
+                    fail('uploadDraftId does not belong to the active workspace.');
+                }
+                if (validDraft.taskId !== id) {
+                    fail('uploadDraftId does not belong to this task.');
+                }
+                if (validDraft.actorRef !== deps.getActorRef()) {
+                    fail('uploadDraftId was created by a different actor and cannot finalize this attachment.');
+                }
+                const normalizedUploadedPath = deps.normalizeStoragePath(uploadedPath.trim());
+                if (!normalizedUploadedPath) {
+                    fail('uploadedPath must be a valid Taskforce storage path.');
+                }
+                const storagePath = normalizedUploadedPath;
+                if (validDraft.storageKey !== storagePath) {
+                    fail('uploadedPath does not match the staged upload draft.');
+                }
+                if (deps.inferWorkspaceIdFromStoragePath(storagePath) !== deps.activeWorkspaceId) {
+                    fail('uploadedPath does not belong to the active workspace.');
+                }
+                const uploadTtlSeconds = deps.objectStorageConfig.provider === 'r2' && deps.objectStorageConfig.r2
+                    ? Math.max(1, Math.floor(deps.objectStorageConfig.r2.signedUploadTtlSeconds))
+                    : 0;
+                if (uploadTtlSeconds > 0) {
+                    const draftCreatedAtMs = Date.parse(validDraft.createdAt);
+                    if (Number.isFinite(draftCreatedAtMs) && nowValue.getTime() > draftCreatedAtMs + uploadTtlSeconds * 1000) {
+                        deps.discardUploadDraft(validDraft.draftId);
+                        await objectStorageClient.deleteObject(storagePath).catch(() => { });
+                        fail('uploadDraftId has expired. Start a new staged upload.');
+                    }
+                }
+                const uploadedObject = await objectStorageClient.getObject(storagePath);
+                if (!uploadedObject) {
+                    deps.discardUploadDraft(validDraft.draftId);
+                    fail(`Uploaded file not found: ${storagePath}`);
+                }
+                const uploaded = uploadedObject;
+                if (safeFilename !== validDraft.originalFilename) {
+                    fail('filename does not match the staged upload draft.');
+                }
+                const draftMimeType = String(validDraft.mimeType || '').trim().toLowerCase() || 'application/octet-stream';
+                if (safeMimeType && safeMimeType !== draftMimeType) {
+                    fail('mimeType does not match the staged upload draft.');
+                }
+                const uploadedContentType = String(uploaded.contentType || '').trim().toLowerCase();
+                if (uploadedContentType && uploadedContentType !== draftMimeType) {
+                    fail('Uploaded object content type does not match the staged upload draft.');
+                }
+                if (uploaded.body.length !== validDraft.sizeBytes) {
+                    fail('Uploaded object size does not match the staged upload draft.');
+                }
+                integrity = deps.verifyIntegrity(uploaded.body, expectedSizeBytes, expectedSha256);
+                const resolvedMimeType = draftMimeType || uploadedContentType || deps.inferMimeType(safeFilename);
+                if (storagePath.endsWith('.md') || storagePath.endsWith('.markdown')) {
+                    const validation = deps.validateStructuredDocument(storagePath, uploaded.body.toString('utf8'));
+                    if (!validation.ok)
+                        fail(validation.message);
+                }
+                const scan = await deps.scanBuffer(uploaded.body);
+                if (scan.verdict === 'infected') {
+                    await objectStorageClient.deleteObject(storagePath).catch(() => { });
+                    fail('File rejected by virus scanner.');
+                }
+                if (scan.verdict === 'error' && scan.failClosed) {
+                    fail('Virus scan failed. Upload blocked.');
+                }
+                const kind = deps.inferAssetKind(safeFilename, resolvedMimeType);
+                const embeddedAssetId = storagePath.match(/(^|\/)(asset-[a-f0-9]{32})(?=[^/]*$)/i)?.[2] || null;
+                const existingUploadedAsset = workspaceAssetStore.getByStorageKey(storagePath, deps.activeWorkspaceId);
+                const isMarkdownDocument = storagePath.toLowerCase().endsWith('.md') || storagePath.toLowerCase().endsWith('.markdown');
+                const overwriteTitle = overwriteTarget
+                    ? deps.workspaceAssetStore?.getDocument?.(overwriteTarget.asset.assetId, deps.activeWorkspaceId)?.title
+                    : null;
+                const canonicalName = safeCaption || overwriteTitle || overwriteTarget?.asset.logicalName
+                    || existingUploadedAsset?.logicalName || safeFilename;
+                const persistedCaption = isMarkdownDocument
+                    ? canonicalName
+                    : (safeCaption || overwriteTarget?.attachment.caption || safeFilename);
+                replacedStorageKey = [overwriteTarget?.asset.storageKey, overwriteTarget?.attachment.fsPath]
+                    .find((candidate) => !!candidate && candidate !== storagePath) || null;
+                const contentSha256 = createHash('sha256').update(uploaded.body).digest('hex');
+                const currentDocumentAsset = overwriteTarget?.asset || existingUploadedAsset;
+                documentContentUnchanged = kind === 'document'
+                    && !!currentDocumentAsset
+                    && currentDocumentAsset.contentSha256 === contentSha256;
+                documentVersionCreated = kind === 'document' && !documentContentUnchanged;
+                asset = workspaceAssetStore.upsertAsset({
+                    assetId: overwriteTarget?.asset.assetId || existingUploadedAsset?.assetId || embeddedAssetId || `asset-${randomUUID().replace(/-/g, '')}`,
+                    workspaceId: deps.activeWorkspaceId,
+                    kind,
+                    logicalName: canonicalName,
+                    originalFilename: safeFilename,
+                    mimeType: resolvedMimeType,
+                    storageProvider: 'r2',
+                    storageKey: storagePath,
+                    contentSha256,
+                    sizeBytes: uploaded.body.length,
+                    documentId: kind === 'document'
+                        ? (overwriteTarget?.asset.documentId || existingUploadedAsset?.documentId || `doc-${randomUUID().replace(/-/g, '')}`)
+                        : null,
+                    version: kind === 'document'
+                        ? Math.max(1, Number(currentDocumentAsset?.version || 0) + (documentContentUnchanged ? 0 : 1))
+                        : null,
+                    isLatest: true,
+                    scanStatus: deps.scanStatus(scan.verdict),
+                    scanEngine: scan.engine || null,
+                    scanDetails: scan.details || null,
+                    createdByUserId: overwriteTarget?.asset.createdByUserId || deps.getActorRef(),
+                    createdAt: overwriteTarget?.asset.createdAt || existingUploadedAsset?.createdAt || now,
+                    updatedAt: now,
+                    deletedAt: null,
+                    purgeAfter: null,
+                });
+                const publishedContentMatches = deps.hasPublishedContentVersion
+                    ? deps.hasPublishedContentVersion(asset)
+                    : true;
+                if (!documentContentUnchanged || replacedStorageKey || !publishedContentMatches) {
+                    await deps.publishContentVersion({ asset, body: uploaded.body, sourceUpdatedAt: now });
+                }
+                if (!durableAttachmentLinksEnabled) {
+                    workspaceAssetStore.upsertLink({
+                        workspaceId: deps.activeWorkspaceId,
+                        assetId: asset.assetId,
+                        taskId: id,
+                        role: 'attachment',
+                        displayName: kind === 'document' ? null : safeDisplayName,
+                        updatedAt: now,
+                        deletedAt: null,
+                    });
+                }
+                consumedUploadDraftId = validDraft.draftId;
+                attachment = buildAttachmentRecord(asset, storagePath);
+                storageKeyForAudit = storagePath;
+            }
+            else {
+                const canonicalAsset = overwriteTarget
+                    ? null
+                    : deps.canonicalAssetHelpers.buildCanonicalWorkspaceAssetRelativePath({
+                        workspaceIdRaw: deps.activeWorkspaceId,
+                        kind: deps.inferAssetKind(safeFilename, deps.inferMimeType(safeFilename)),
+                        filename: safeFilename,
+                        assetId: stableAttachmentAssetId,
+                    });
+                const destinationPath = overwriteTarget
+                    ? overwriteTarget.absolutePath
+                    : path.join(basePath, canonicalAsset.relativePath);
+                fs.mkdirSync(path.dirname(destinationPath), { recursive: true });
+                if (hasContent) {
+                    integrity = deps.verifyIntegrity(Buffer.from(content, 'utf8'), expectedSizeBytes, expectedSha256);
+                    fs.writeFileSync(destinationPath, content, 'utf8');
+                }
+                else {
+                    const trimmedSource = sourcePath.trim();
+                    const sourceResolved = path.isAbsolute(trimmedSource)
+                        ? path.resolve(trimmedSource)
+                        : path.resolve(projectRoot, trimmedSource);
+                    if (!fs.existsSync(sourceResolved))
+                        fail(`File not found: ${trimmedSource}`);
+                    const sourceReal = fs.realpathSync(sourceResolved);
+                    const projectRootReal = fs.realpathSync(projectRoot);
+                    if (!deps.isApprovedSourcePath(sourceReal, projectRootReal)) {
+                        fail("sourcePath must be within project root, a registered Git worktree, a Taskforce-managed source, an approved agent workspace, or the bound profile's QA artifacts root");
+                    }
+                    if (!fs.statSync(sourceReal).isFile())
+                        fail(`Path is not a file: ${trimmedSource}`);
+                    integrity = deps.verifyIntegrity(fs.readFileSync(sourceReal), expectedSizeBytes, expectedSha256);
+                    fs.copyFileSync(sourceReal, destinationPath);
+                }
+                const relativePath = overwriteTarget
+                    ? overwriteTarget.relativePath
+                    : deps.toPosixPath(path.relative(projectRoot, destinationPath));
+                if (relativePath.endsWith('.md')) {
+                    const validation = deps.validateStructuredDocument(relativePath, fs.readFileSync(destinationPath, 'utf8'));
+                    if (!validation.ok)
+                        fail(validation.message);
+                }
+                const isMarkdownDocument = relativePath.toLowerCase().endsWith('.md') || relativePath.toLowerCase().endsWith('.markdown');
+                const overwriteTitle = overwriteTarget
+                    ? deps.workspaceAssetStore?.getDocument?.(overwriteTarget.asset.assetId, deps.activeWorkspaceId)?.title
+                    : null;
+                const canonicalName = safeCaption || overwriteTitle || overwriteTarget?.asset.logicalName || safeFilename;
+                const persistedCaption = isMarkdownDocument
+                    ? canonicalName
+                    : (safeCaption || overwriteTarget?.attachment.caption || safeFilename);
+                asset = await deps.canonicalAssetHelpers.ensureCanonicalTaskAttachment(relativePath, id, persistedCaption, now, 'attachment', {
+                    originalFilename: safeFilename,
+                    logicalName: canonicalName,
+                    displayName: safeDisplayName,
+                    ...(!overwriteTarget ? { assetId: stableAttachmentAssetId } : {}),
+                    ...(overwriteTarget
+                        ? {
+                            assetId: overwriteTarget.asset.assetId,
+                            documentId: overwriteTarget.asset.documentId,
+                            createdAt: overwriteTarget.asset.createdAt,
+                            createdByUserId: overwriteTarget.asset.createdByUserId,
+                            scanStatus: overwriteTarget.asset.scanStatus,
+                            scanEngine: overwriteTarget.asset.scanEngine,
+                            scanDetails: overwriteTarget.asset.scanDetails,
+                        }
+                        : { createdByUserId: deps.getActorRef() }),
+                    ...(durableAttachmentLinksEnabled ? { createLink: false } : {}),
+                });
+                documentContentUnchanged = Boolean(overwriteTarget
+                    && asset?.kind === 'document'
+                    && overwriteTarget.asset.contentSha256 === integrity?.sha256);
+                documentVersionCreated = asset?.kind === 'document' && !documentContentUnchanged;
+                attachment = buildAttachmentRecord(asset, canonicalAsset?.relativePath || overwriteTarget?.descriptor.fsPath || relativePath);
+                storageKeyForAudit = String(attachment.fsPath || '');
+            }
+            const existing = Array.isArray(task.attachments) ? task.attachments : [];
+            if (overwriteTarget) {
+                deps.replaceAttachments(id, existing.map((item, index) => index === overwriteTarget.index ? attachment : item), `save-task-attachment-overwrite:${asset?.assetId || overwriteTarget.descriptor.attachmentId}`);
+                if (consumedUploadDraftId)
+                    deps.consumeUploadDraft(consumedUploadDraftId);
+                if (replacedStorageKey) {
+                    if (overwriteTarget.asset.storageProvider === 'r2' && deps.objectStorageClient) {
+                        await deps.objectStorageClient.deleteObject(replacedStorageKey).catch(() => { });
+                    }
+                    else if (overwriteTarget.asset.storageProvider === 'local') {
+                        const replacedAbsolutePath = deps.resolveStoragePathInsideRoot(basePath, replacedStorageKey);
+                        if (replacedAbsolutePath && fs.existsSync(replacedAbsolutePath)) {
+                            fs.rmSync(replacedAbsolutePath, { force: true });
+                        }
+                    }
+                }
+                return {
+                    kind: 'saved',
+                    outcome: 'overwritten',
+                    taskId: id,
+                    task,
+                    attachment,
+                    asset,
+                    integrity,
+                    storageKeyForAudit,
+                    auditAttachmentId: asset?.assetId || overwriteTarget.descriptor.attachmentId,
+                    ...(asset?.kind === 'document' ? {
+                        unchanged: documentContentUnchanged,
+                        versionCreated: documentVersionCreated,
+                    } : {}),
+                };
+            }
+            const duplicate = existing.some((item) => {
+                if (typeof item === 'string')
+                    return item === attachment.path || item === attachment.fsPath;
+                if (!item || typeof item !== 'object')
+                    return false;
+                return item.path === attachment.path || item.fsPath === attachment.fsPath;
+            });
+            if (duplicate) {
+                if (consumedUploadDraftId)
+                    deps.consumeUploadDraft(consumedUploadDraftId);
+                return {
+                    kind: 'saved',
+                    outcome: 'duplicate',
+                    taskId: id,
+                    task,
+                    attachment,
+                    asset,
+                    integrity,
+                    storageKeyForAudit,
+                };
+            }
+            deps.replaceAttachments(id, [...existing, attachment], `save-task-attachment:${asset?.assetId || storageKeyForAudit}`);
+            if (consumedUploadDraftId)
+                deps.consumeUploadDraft(consumedUploadDraftId);
+            return {
+                kind: 'saved',
+                outcome: 'attached',
+                taskId: id,
+                task,
+                attachment,
+                asset,
+                integrity,
+                storageKeyForAudit,
+                ...(asset?.kind === 'document' ? {
+                    unchanged: false,
+                    versionCreated: true,
+                } : {}),
+            };
+        },
+        delete(input) {
+            const { taskId: inputTaskId, attachmentId } = input;
+            if (!attachmentId || typeof attachmentId !== 'string')
+                fail('attachmentId is required');
+            const normalizedAttachmentId = attachmentId;
+            const { id, task } = deps.resolveTask(inputTaskId);
+            const existing = Array.isArray(task.attachments) ? task.attachments : [];
+            const descriptors = deps.taskAttachmentHelpers.listTaskAttachmentDescriptors(task);
+            const targetIndex = descriptors.findIndex((entry) => entry.attachmentId === normalizedAttachmentId);
+            if (targetIndex < 0) {
+                fail(`Attachment ${normalizedAttachmentId} not found on task ${inputTaskId}`, 'MCP_NOT_FOUND', 404);
+            }
+            const targetDescriptor = descriptors[targetIndex];
+            const targetAssetLink = targetDescriptor.assetId && deps.workspaceAssetStore
+                ? deps.workspaceAssetStore.listLinksForTarget('task', id, deps.activeWorkspaceId)
+                    .find((link) => link.assetId === targetDescriptor.assetId)
+                : null;
+            deps.replaceAttachments(id, existing.filter((_, index) => index !== targetIndex), `delete-task-attachment:${targetDescriptor.assetId || normalizedAttachmentId}`);
+            let canonicalAssetDeleted = false;
+            let deletedAnnotatedSessions = 0;
+            if (targetDescriptor.source === 'canonical' && targetDescriptor.assetId && deps.workspaceAssetStore) {
+                const deletedAt = nowDate().toISOString();
+                const remainingLinks = deps.workspaceAssetStore.listLinksForAsset(targetDescriptor.assetId, deps.activeWorkspaceId);
+                if (targetAssetLink?.role !== 'reference' && remainingLinks.length === 0) {
+                    const deletedAsset = deps.workspaceAssetStore.markDeleted(targetDescriptor.assetId, deps.activeWorkspaceId, deletedAt, null);
+                    canonicalAssetDeleted = true;
+                    if (deletedAsset?.kind === 'image') {
+                        deletedAnnotatedSessions = deps.deleteAnnotatedSessionsForImage({
+                            workspaceId: deps.activeWorkspaceId,
+                            imageAssetId: targetDescriptor.assetId,
+                            deletedAt,
+                        });
+                    }
+                }
+            }
+            return { taskId: id, task, attachmentId: normalizedAttachmentId, canonicalAssetDeleted, deletedAnnotatedSessions };
+        },
+    };
+}