feat(tickets,comments): support HTML rich-text descriptions and comments - #30
Merged
Conversation
Asana's API stores markdown verbatim as plaintext in notes/text, so markdown written by callers of create_ticket/update_ticket/add_comment was previously rendered literally instead of formatted. Add optional description_html (tickets) and text_html (comments) parameters mapped to Asana's html_notes/html_text fields, mutually exclusive with the plain-text field, so callers can opt into rich formatting or @-mentions without server-side markdown conversion. Ref: CODE-1176
Docs alone don't reliably stop an agent from writing Markdown into description/text out of habit. Add a lightweight heuristic (looksLikeMarkdown) that flags headings, bold/italic, inline/fenced code, links, and blockquotes (deliberately not dash-bulleted lists, since those still read fine unconverted), and surface a warning in the mutation result nudging the caller toward description_html/ text_html instead. The write still succeeds; this is a same-turn corrective nudge, not a rejection.
janszopinski-asana
approved these changes
Sep 4, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
description_htmltocreate_ticket/update_ticket(maps to Asana'shtml_notes) andtext_htmltoadd_comment(maps tohtml_text), each mutually exclusive with its plain-text counterpart.description/textwas sent to Asana verbatim and stored as literal text, since Asana's API does not render Markdown. Callers can now opt into rich formatting or@-mentions via the new HTML fields instead.description_html/text_htmlcompares against the raw re-readhtml_notes/html_textfield rather than the projected plain-text view, so writes are verified correctly.looksLikeMarkdownheuristic (src/markdown_heuristic.ts) that flags headings, bold/italic, inline/fenced code, links, and blockquotes in the plain-textdescription/textfields (deliberately excluding dash-bulleted lists, since those still read fine unconverted) and surfaces a same-turn warning in the mutation result nudging the caller towarddescription_html/text_html. The write still succeeds — this is a corrective nudge for callers that don't follow the parameter docs, not a rejection.Test plan
npm run typechecknpm run lintnpm test(359 tests passing, including coverage for create/update withdescription_html, verification mismatch cases, mutual-exclusivity rejection,add_commentwithtext_html, and the Markdown-heuristic warnings on both tools)npm run build🤖 Generated with Claude Code