@hauptsache.net/clickup-mcp 1.6.2 → 1.7.2

package/dist/clickup-text.js

@@ -5,6 +5,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.convertClickUpTextItemsToToolCallResult = convertClickUpTextItemsToToolCallResult;
 exports.convertMarkdownToToolCallResult = convertMarkdownToToolCallResult;
+exports.buildImageFragment = buildImageFragment;
+exports.parseClickUpTaskUrl = parseClickUpTaskUrl;
+exports.normalizeImageDestinations = normalizeImageDestinations;
+exports.collectMarkdownImageSources = collectMarkdownImageSources;
+exports.rewriteMarkdownImageUrls = rewriteMarkdownImageUrls;
 exports.convertMarkdownToClickUpBlocks = convertMarkdownToClickUpBlocks;
 const data_uri_1 = require("./shared/data-uri");
 const unified_1 = require("unified");
@@ -31,6 +36,18 @@ function extractThumbnailsFromDataAttachment(attributes) {
         return {};
     }
 }
+/**
+ * Render an image reference as markdown, escaping whatever would break the syntax.
+ *
+ * Reading and writing use the same markdown here on purpose: it lets an agent feed a
+ * comment it just read straight back into editComment without losing the images.
+ */
+function toMarkdownImage(alt, url) {
+    const safeAlt = alt.replace(/[\[\]\r\n]/g, " ").trim();
+    // Angle brackets let a URL with spaces or parentheses survive the round trip
+    const safeUrl = /[\s()]/.test(url) ? `<${url}>` : url;
+    return `![${safeAlt}](${safeUrl})`;
+}
 /**
  * Process an array of ClickUp text items into a structured content format
  * that includes both text and images in their original sequence
@@ -45,11 +62,24 @@ async function convertClickUpTextItemsToToolCallResult(textItems) {
     // Track current formatting state to avoid unnecessary close/reopen
     let activeBold = false;
     let activeItalic = false;
+    let activeStrike = false;
     let activeCode = false;
+    // ClickUp emits one '\n' fragment with a code-block attribute per code LINE;
+    // consecutive ones belong to the same fenced block when read back as markdown.
+    let inCodeBlock = false;
+    let currentFenceLang = '';
+    const closeCodeFence = () => {
+        if (inCodeBlock) {
+            currentTextBlock += '```\n';
+            inCodeBlock = false;
+            currentFenceLang = '';
+        }
+    };
     for (let i = 0; i < textItems.length; i++) {
         const item = textItems[i];
         // Handle image items
         if (item.type === "image" && item.image && item.image.url) {
+            closeCodeFence();
             const imageFileName = item.image.name || item.image.title || "image";
             const imageUrl = item.image.url;
             const altText = item.text || imageFileName;
@@ -80,8 +110,10 @@ async function convertClickUpTextItemsToToolCallResult(textItems) {
                 }
                 continue;
             }
-            // Add image URL reference inline to current text block
-            currentTextBlock += `\nImage: ${imageFileName} - ${imageUrl}`;
+            // Reference the image in the same markdown syntax the write tools accept, so a
+            // comment read here can be handed back to editComment unchanged and keep its
+            // images - an existing ClickUp attachment URL is re-embedded without re-uploading.
+            currentTextBlock += `\n${toMarkdownImage(altText, imageUrl)}`;
             // Get working thumbnail URLs from data-attachment if available
             const extractedThumbnails = extractThumbnailsFromDataAttachment(item.attributes);
             // Determine best thumbnail URLs (prefer extracted over API thumbnails)
@@ -114,6 +146,27 @@ async function convertClickUpTextItemsToToolCallResult(textItems) {
         else if (typeof item.text === "string") {
             // Check if this is a newline with block formatting (header, blockquote, list)
             if (item.text === '\n' && item.attributes) {
+                // Code block formatting: append this line to the open fence (or open one).
+                // The attribute value carries the language, either directly or nested as
+                // {'code-block': lang}; 'plain' means no language.
+                if (item.attributes['code-block']) {
+                    const rawLang = item.attributes['code-block'];
+                    const lang = typeof rawLang === 'string' ? rawLang : rawLang?.['code-block'] ?? '';
+                    const fenceLang = lang === 'plain' ? '' : lang;
+                    if (inCodeBlock && fenceLang !== currentFenceLang) {
+                        closeCodeFence();
+                    }
+                    if (!inCodeBlock) {
+                        currentTextBlock += '```' + fenceLang + '\n';
+                        inCodeBlock = true;
+                        currentFenceLang = fenceLang;
+                    }
+                    currentTextBlock += currentLine + '\n';
+                    currentLine = "";
+                    continue;
+                }
+                // Any other line terminator ends a code block
+                closeCodeFence();
                 // Header formatting
                 if (item.attributes.header) {
                     const level = item.attributes.header;
@@ -144,17 +197,8 @@ async function convertClickUpTextItemsToToolCallResult(textItems) {
                             break;
                     }
                 }
-                // Code block formatting
-                else if (item.attributes['code-block']) {
-                    // Wrap the current line in code block markers
-                    currentLine = '```\n' + currentLine + '\n```';
-                }
                 // Add formatted line to text block
-                currentTextBlock += currentLine;
-                // Add newline unless it's code block (already has newlines)
-                if (!item.attributes['code-block']) {
-                    currentTextBlock += '\n';
-                }
+                currentTextBlock += currentLine + '\n';
                 currentLine = ""; // Reset for next line
                 continue;
             }
@@ -163,15 +207,18 @@ async function convertClickUpTextItemsToToolCallResult(textItems) {
             // Determine current and next formatting state
             const hasBold = item.attributes?.bold === true;
             const hasItalic = item.attributes?.italic === true;
+            const hasStrike = item.attributes?.strike === true;
             const hasLink = item.attributes?.link;
             // Look ahead to next non-newline block
             let nextHasBold = false;
             let nextHasItalic = false;
+            let nextHasStrike = false;
             for (let j = i + 1; j < textItems.length; j++) {
                 const nextItem = textItems[j];
                 if (nextItem.text !== '\n' || !nextItem.attributes) {
                     nextHasBold = nextItem.attributes?.bold === true;
                     nextHasItalic = nextItem.attributes?.italic === true;
+                    nextHasStrike = nextItem.attributes?.strike === true;
                     break;
                 }
             }
@@ -181,14 +228,20 @@ async function convertClickUpTextItemsToToolCallResult(textItems) {
                 prefix += "**";
             if (hasItalic && !activeItalic)
                 prefix += "*";
+            if (hasStrike && !activeStrike)
+                prefix += "~~";
             // Build suffix (close formatting that won't continue)
             let suffix = "";
+            if (hasStrike && !nextHasStrike)
+                suffix += "~~";
             if (hasItalic && !nextHasItalic)
                 suffix += "*";
             if (hasBold && !nextHasBold)
                 suffix += "**";
             // Close formatting that's active but not in this block
             let closingPrefix = "";
+            if (activeStrike && !hasStrike)
+                closingPrefix += "~~";
             if (activeBold && !hasBold)
                 closingPrefix += "**";
             if (activeItalic && !hasItalic)
@@ -197,6 +250,7 @@ async function convertClickUpTextItemsToToolCallResult(textItems) {
             // Update state
             activeBold = hasBold && nextHasBold;
             activeItalic = hasItalic && nextHasItalic;
+            activeStrike = hasStrike && nextHasStrike;
             // Link formatting (wraps everything)
             if (hasLink) {
                 formattedText = `[${formattedText}](${hasLink})`;
@@ -208,6 +262,7 @@ async function convertClickUpTextItemsToToolCallResult(textItems) {
             // Add to current line (not text block yet)
             if (item.text === '\n') {
                 // Plain newline without formatting
+                closeCodeFence();
                 currentTextBlock += currentLine + '\n';
                 currentLine = "";
             }
@@ -215,12 +270,18 @@ async function convertClickUpTextItemsToToolCallResult(textItems) {
                 currentLine += formattedText;
             }
         }
+        // Task mentions render as the task URL so the reference survives the round trip:
+        // writing that URL back through addComment/editComment regenerates the mention.
+        else if (item.type === "task_mention" && item.task_mention?.task_id) {
+            currentLine += `https://app.clickup.com/t/${item.task_mention.task_id}`;
+        }
         // Handle other types of items like bookmarks or whatever clickup can think of
         else {
             currentTextBlock += JSON.stringify(item);
         }
     }
     // Add any remaining text
+    closeCodeFence();
     if (currentLine) {
         currentTextBlock += currentLine;
     }
@@ -288,9 +349,9 @@ function convertMarkdownToToolCallResult(markdownText, attachments) {
         // Check if this image URL exists in our attachments
         const attachment = attachmentMap.get(imageUrl);
         if (attachment) {
-            // Add image URL reference inline to current text block
+            // Keep the markdown syntax, so the reference stays usable in a write call
             const imageFileName = altText || "image";
-            currentTextBlock += `\nImage: ${imageFileName} - ${imageUrl}`;
+            currentTextBlock += `\n${toMarkdownImage(imageFileName, imageUrl)}`;
             // Only create image_metadata if we have at least one thumbnail (never use original image)
             if (attachment.thumbnail_large || attachment.thumbnail_medium || attachment.thumbnail_small) {
                 // Push accumulated text (including image URL) as a text block
@@ -380,14 +441,132 @@ function extractFileTypeFromUrl(url) {
         return null;
     return filename.substring(lastDot + 1);
 }
+/**
+ * Build the image fragment ClickUp needs to render an inline image in a comment.
+ * `title`/`text` carry the caption; the rest is copied straight from the upload response.
+ */
+function buildImageFragment(attachment, caption) {
+    const label = caption || attachment.name || 'image';
+    const fragment = {
+        type: 'image',
+        text: label,
+        image: {
+            id: attachment.id,
+            name: attachment.name,
+            title: label,
+            extension: attachment.extension,
+            url: attachment.url,
+            thumbnail_small: attachment.thumbnail_small,
+            thumbnail_medium: attachment.thumbnail_medium,
+            thumbnail_large: attachment.thumbnail_large,
+            width: attachment.width,
+            height: attachment.height,
+        },
+    };
+    if (caption) {
+        fragment.attributes = { alt: caption };
+    }
+    return fragment;
+}
+/**
+ * Matches a plain ClickUp task URL, with or without the team segment:
+ * https://app.clickup.com/t/86cb3t6t2 or https://app.clickup.com/t/4500611/86cb3t6t2
+ *
+ * Deliberately narrow: custom task IDs (PREFIX-123) and URLs carrying a query or
+ * fragment (e.g. ?comment=... deep links) do NOT match, because a mention would
+ * either not resolve or lose the anchor - those stay ordinary links.
+ */
+const CLICKUP_TASK_URL_PATTERN = /^https?:\/\/app\.clickup\.com\/t\/(?:\d+\/)?([a-z0-9]{6,12})\/?$/;
+/**
+ * Extract the task ID from a ClickUp task URL, or null if it is not one.
+ */
+function parseClickUpTaskUrl(url) {
+    const match = url.match(CLICKUP_TASK_URL_PATTERN);
+    return match ? match[1] : null;
+}
+/**
+ * Wrap image destinations that contain spaces in angle brackets.
+ *
+ * CommonMark rejects a bare destination with spaces, so `![x](/tmp/Screen Shot.png)`
+ * is not an image at all - it would silently stay literal text and never be uploaded.
+ * Screenshot filenames have spaces constantly ("Screenshot 2026-07-27 at 14.30.png"),
+ * so normalising to the `<...>` form is what makes the obvious thing work.
+ */
+function normalizeImageDestinations(markdown) {
+    return markdown.replace(/!\[([^\]]*)\]\(([^)\n]*)\)/g, (match, alt, inner) => {
+        const trimmed = inner.trim();
+        // Already bracketed, or nothing to fix
+        if (trimmed.startsWith('<') || trimmed.includes('>')) {
+            return match;
+        }
+        // Split off an optional markdown title: dest "title" / 'title'
+        const titleMatch = trimmed.match(/^(.*?)(\s+(?:"[^"]*"|'[^']*'))$/s);
+        const dest = titleMatch ? titleMatch[1] : trimmed;
+        const title = titleMatch ? titleMatch[2] : '';
+        if (!dest || !/\s/.test(dest)) {
+            return match;
+        }
+        return `![${alt}](<${dest}>${title})`;
+    });
+}
+/**
+ * Collect every image reference in a markdown document, in document order.
+ * Callers use this to know what needs uploading before converting.
+ */
+function collectMarkdownImageSources(markdown) {
+    const images = [];
+    try {
+        const tree = (0, unified_1.unified)()
+            .use(remark_parse_1.default)
+            .use(remark_gfm_1.default)
+            .parse(markdown);
+        const visit = (nodes) => {
+            for (const node of nodes) {
+                if (node.type === 'image' && typeof node.url === 'string') {
+                    images.push({ src: node.url, alt: typeof node.alt === 'string' ? node.alt : '' });
+                }
+                else if (Array.isArray(node.children)) {
+                    visit(node.children);
+                }
+            }
+        };
+        visit(tree.children);
+    }
+    catch (error) {
+        console.error('Failed to collect markdown images:', error);
+    }
+    return images;
+}
+/**
+ * Replace image sources in markdown with their uploaded ClickUp URLs.
+ *
+ * Used for task descriptions: `markdown_description` renders `![alt](url)` directly,
+ * so descriptions need no fragment handling - only the URL has to be swapped.
+ * Images without an upload keep their original source untouched.
+ */
+function rewriteMarkdownImageUrls(markdown, attachmentsBySrc) {
+    if (attachmentsBySrc.size === 0) {
+        return markdown;
+    }
+    return markdown.replace(/!\[([^\]]*)\]\(\s*(<[^>]*>|[^)\s]+)([^)]*)\)/g, (match, alt, rawSrc, trailing) => {
+        const src = rawSrc.startsWith('<') && rawSrc.endsWith('>') ? rawSrc.slice(1, -1) : rawSrc;
+        const attachment = attachmentsBySrc.get(src);
+        if (!attachment) {
+            return match;
+        }
+        return `![${alt}](${attachment.url}${trailing})`;
+    });
+}
 /**
  * Convert markdown text to ClickUp comment blocks format using remark
- * Supports: headers, bold, italic, code, links, lists, blockquotes, code blocks
+ * Supports: headers, bold, italic, code, links, lists, blockquotes, code blocks, images
  *
  * @param markdown The markdown text to convert
+ * @param attachmentsBySrc Uploaded attachments keyed by the markdown `src` they came from.
+ *   Images without an entry degrade to a link so their information is not lost.
  * @returns Array of ClickUp comment blocks
  */
-function convertMarkdownToClickUpBlocks(markdown) {
+function convertMarkdownToClickUpBlocks(markdown, attachmentsBySrc) {
     const blocks = [];
     try {
         // Parse the entire markdown document using remark with GFM support (for task lists)
@@ -396,7 +575,7 @@ function convertMarkdownToClickUpBlocks(markdown) {
             .use(remark_gfm_1.default)
             .parse(markdown);
         // Walk the tree recursively
-        walkMdastNodes(tree.children, {}, blocks);
+        walkMdastNodes(tree.children, {}, blocks, 0, attachmentsBySrc);
     }
     catch (error) {
         console.error('Failed to parse markdown:', error);
@@ -412,20 +591,20 @@ function convertMarkdownToClickUpBlocks(markdown) {
  * @param blocks Output array to append ClickUp blocks to
  * @param depth Nesting depth for lists (0 = top level, 1 = first nest, etc.)
  */
-function walkMdastNodes(nodes, inheritedAttrs, blocks, depth = 0) {
+function walkMdastNodes(nodes, inheritedAttrs, blocks, depth = 0, attachmentsBySrc) {
     for (let i = 0; i < nodes.length; i++) {
         const node = nodes[i];
         const currentAttrs = { ...inheritedAttrs };
         switch (node.type) {
             case 'heading':
                 // Process heading content with inline formatting
-                walkPhrasingContent(node.children, currentAttrs, blocks);
+                walkPhrasingContent(node.children, currentAttrs, blocks, attachmentsBySrc);
                 // Add newline with header attribute
                 blocks.push({ text: '\n', attributes: { header: node.depth } });
                 break;
             case 'paragraph':
                 // Process paragraph content with inline formatting
-                walkPhrasingContent(node.children, currentAttrs, blocks);
+                walkPhrasingContent(node.children, currentAttrs, blocks, attachmentsBySrc);
                 // Add newline unless it's the last node
                 if (i < nodes.length - 1) {
                     blocks.push({ text: '\n', attributes: {} });
@@ -437,7 +616,7 @@ function walkMdastNodes(nodes, inheritedAttrs, blocks, depth = 0) {
                 const blockquoteChildren = node.children;
                 for (const child of blockquoteChildren) {
                     if (child.type === 'paragraph') {
-                        walkPhrasingContent(child.children, currentAttrs, blocks);
+                        walkPhrasingContent(child.children, currentAttrs, blocks, attachmentsBySrc);
                         blocks.push({ text: '\n', attributes: { blockquote: {} } });
                     }
                     // Note: Other child types (heading, list) are not supported by ClickUp blockquotes
@@ -457,7 +636,7 @@ function walkMdastNodes(nodes, inheritedAttrs, blocks, depth = 0) {
                     for (const itemChild of listItem.children) {
                         if (itemChild.type === 'paragraph') {
                             // Process paragraph content with inline formatting
-                            walkPhrasingContent(itemChild.children, currentAttrs, blocks);
+                            walkPhrasingContent(itemChild.children, currentAttrs, blocks, attachmentsBySrc);
                             // Add newline with list formatting and optional indent
                             const listAttrs = {
                                 list: { list: finalListType }
@@ -470,7 +649,7 @@ function walkMdastNodes(nodes, inheritedAttrs, blocks, depth = 0) {
                         }
                         else if (itemChild.type === 'list') {
                             // Nested list - recursively process with increased depth
-                            walkMdastNodes([itemChild], currentAttrs, blocks, depth + 1);
+                            walkMdastNodes([itemChild], currentAttrs, blocks, depth + 1, attachmentsBySrc);
                         }
                     }
                 }
@@ -479,34 +658,148 @@ function walkMdastNodes(nodes, inheritedAttrs, blocks, depth = 0) {
                 // Code block
                 const codeNode = node;
                 if (codeNode.value) {
-                    blocks.push({ text: codeNode.value, attributes: {} });
-                    blocks.push({
-                        text: '\n',
-                        attributes: { 'code-block': { 'code-block': codeNode.lang || 'plain' } }
-                    });
+                    pushCodeBlockLines(blocks, codeNode.value, codeNode.lang || 'plain');
                 }
                 break;
             case 'thematicBreak':
                 // Horizontal rule - just add a line break
                 blocks.push({ text: '\n', attributes: {} });
                 break;
+            case 'table': {
+                // ClickUp comments cannot render tables (there is no table fragment in the
+                // comment format - unknown attributes are stored but render as plain text).
+                // Re-render the table as an aligned pipe table inside a code block so the
+                // information survives and stays readable in monospace.
+                const tableText = serializeTableAsAlignedPipes(node);
+                if (tableText) {
+                    pushCodeBlockLines(blocks, tableText, 'plain');
+                }
+                break;
+            }
             default:
                 // For any other block-level nodes, try to process children
                 if ('children' in node && Array.isArray(node.children)) {
-                    walkMdastNodes(node.children, currentAttrs, blocks, depth);
+                    walkMdastNodes(node.children, currentAttrs, blocks, depth, attachmentsBySrc);
+                }
+                else if ('value' in node && typeof node.value === 'string') {
+                    // Last-resort safety net: never drop text content silently
+                    blocks.push({ text: node.value, attributes: {} });
                 }
                 break;
         }
     }
 }
+/**
+ * Emit a (possibly multi-line) code block the way ClickUp's Quill-based format
+ * expects it: block attributes apply per line, so EVERY line needs its own '\n'
+ * fragment carrying the code-block attribute. A single text fragment with embedded
+ * newlines renders only its last line as code - the rest degrades to plain text.
+ */
+function pushCodeBlockLines(blocks, code, lang) {
+    for (const line of code.split('\n')) {
+        if (line) {
+            blocks.push({ text: line, attributes: {} });
+        }
+        blocks.push({
+            text: '\n',
+            attributes: { 'code-block': { 'code-block': lang } }
+        });
+    }
+}
+/**
+ * Serialize phrasing content back to compact markdown for use inside a code block.
+ * Inline formatting markers are kept so nothing is lost, even though a code block
+ * renders them literally.
+ */
+function serializePhrasingToMarkdown(nodes) {
+    let out = '';
+    for (const node of nodes) {
+        switch (node.type) {
+            case 'text':
+                out += node.value;
+                break;
+            case 'strong':
+                out += `**${serializePhrasingToMarkdown(node.children)}**`;
+                break;
+            case 'emphasis':
+                out += `*${serializePhrasingToMarkdown(node.children)}*`;
+                break;
+            case 'delete':
+                out += `~~${serializePhrasingToMarkdown(node.children)}~~`;
+                break;
+            case 'inlineCode':
+                out += `\`${node.value}\``;
+                break;
+            case 'link':
+                out += `[${serializePhrasingToMarkdown(node.children)}](${node.url})`;
+                break;
+            case 'image':
+                out += node.alt || node.url;
+                break;
+            case 'break':
+                out += ' ';
+                break;
+            default:
+                if ('value' in node && typeof node.value === 'string') {
+                    out += node.value;
+                }
+                else if ('children' in node && Array.isArray(node.children)) {
+                    out += serializePhrasingToMarkdown(node.children);
+                }
+                break;
+        }
+    }
+    return out;
+}
+/**
+ * Render an mdast table as a column-aligned pipe table string.
+ */
+function serializeTableAsAlignedPipes(table) {
+    const rows = table.children.map((row) => row.children.map((cell) => serializePhrasingToMarkdown(cell.children).replace(/\|/g, '\\|').trim()));
+    if (rows.length === 0) {
+        return '';
+    }
+    const colCount = Math.max(...rows.map((r) => r.length));
+    const widths = [];
+    for (let col = 0; col < colCount; col++) {
+        widths[col] = Math.max(3, ...rows.map((r) => (r[col] ?? '').length));
+    }
+    const renderRow = (cells) => '| ' + widths.map((w, col) => (cells[col] ?? '').padEnd(w)).join(' | ') + ' |';
+    const lines = [renderRow(rows[0])];
+    lines.push('| ' + widths.map((w) => '-'.repeat(w)).join(' | ') + ' |');
+    for (const row of rows.slice(1)) {
+        lines.push(renderRow(row));
+    }
+    return lines.join('\n');
+}
 /**
  * Recursively walk phrasing content (inline nodes) and build ClickUp blocks
  * Accumulates formatting attributes from parent nodes
  */
-function walkPhrasingContent(nodes, inheritedAttrs, blocks) {
+function walkPhrasingContent(nodes, inheritedAttrs, blocks, attachmentsBySrc) {
     for (const node of nodes) {
         const currentAttrs = { ...inheritedAttrs };
         switch (node.type) {
+            case 'image': {
+                // An image node has neither `value` nor `children`, so without this case it
+                // would fall through to `default` and vanish silently.
+                const attachment = attachmentsBySrc?.get(node.url);
+                const caption = node.alt || '';
+                if (attachment) {
+                    blocks.push(buildImageFragment(attachment, caption));
+                }
+                else {
+                    // Nothing was uploaded for this source - degrade to a link rather than
+                    // dropping the reference, so the information survives.
+                    const label = caption || node.url;
+                    const isEmbeddable = /^https?:\/\//i.test(node.url);
+                    blocks.push({
+                        text: label,
+                        attributes: isEmbeddable ? { ...currentAttrs, link: node.url } : currentAttrs,
+                    });
+                }
+                break;
+            }
             case 'text':
                 // Plain text node
                 if (node.value) {
@@ -519,12 +812,17 @@ function walkPhrasingContent(nodes, inheritedAttrs, blocks) {
             case 'strong':
                 // Bold text - recurse with bold attribute
                 currentAttrs.bold = true;
-                walkPhrasingContent(node.children, currentAttrs, blocks);
+                walkPhrasingContent(node.children, currentAttrs, blocks, attachmentsBySrc);
                 break;
             case 'emphasis':
                 // Italic text - recurse with italic attribute
                 currentAttrs.italic = true;
-                walkPhrasingContent(node.children, currentAttrs, blocks);
+                walkPhrasingContent(node.children, currentAttrs, blocks, attachmentsBySrc);
+                break;
+            case 'delete':
+                // GFM strikethrough (~~text~~) - ClickUp renders this via the strike attribute
+                currentAttrs.strike = true;
+                walkPhrasingContent(node.children, currentAttrs, blocks, attachmentsBySrc);
                 break;
             case 'inlineCode':
                 // Inline code
@@ -536,11 +834,20 @@ function walkPhrasingContent(nodes, inheritedAttrs, blocks) {
                     });
                 }
                 break;
-            case 'link':
-                // Link - recurse with link attribute
+            case 'link': {
+                // A link to a ClickUp task becomes a real task mention, matching what the
+                // ClickUp UI does when a task URL is pasted. The mention renders the live
+                // task name, so any custom link text is intentionally replaced by it.
+                const mentionedTaskId = parseClickUpTaskUrl(node.url);
+                if (mentionedTaskId) {
+                    blocks.push({ type: 'task_mention', task_mention: { task_id: mentionedTaskId } });
+                    break;
+                }
+                // Ordinary link - recurse with link attribute
                 currentAttrs.link = node.url;
-                walkPhrasingContent(node.children, currentAttrs, blocks);
+                walkPhrasingContent(node.children, currentAttrs, blocks, attachmentsBySrc);
                 break;
+            }
             case 'break':
                 // Line break - add as plain text
                 blocks.push({ text: '\n', attributes: {} });
@@ -555,7 +862,7 @@ function walkPhrasingContent(nodes, inheritedAttrs, blocks) {
                 }
                 else if ('children' in node && Array.isArray(node.children)) {
                     // Recurse into children for other container nodes
-                    walkPhrasingContent(node.children, currentAttrs, blocks);
+                    walkPhrasingContent(node.children, currentAttrs, blocks, attachmentsBySrc);
                 }
                 break;
         }