,
,
, , -
-,
. For multi-paragraph prose, drop the html flag and send plain text with real newlines.`,
);
}
return problems;
}
export const addCommentTool: ToolDefinition = {
name: "asana_add_comment",
label: ADD_COMMENT_TITLE,
description: ADD_COMMENT_DESCRIPTION,
parameters: Params,
async execute(
_toolCallId: string,
params: Static,
_signal,
_onUpdate,
ctx,
): Promise> {
// Fail fast on malformed html_text BEFORE the review prompt and before
// any task lookup. Asana's silent literal-text fallback gives no HTTP
// signal, so refusing here is the only way to keep broken HTML out of the
// workspace. Plain-text mode (html falsy) is never validated: a literal
// "<" in prose is the caller's intent. Image paths get the same treatment:
// a missing file or unsupported type is a local fact, so it is reported
// before the user is asked to review a doomed comment.
if (params.html) {
const problems = validateHtmlText(params.text);
if (problems.length > 0) {
return toToolResult(
`Asana: refused to post html_text (task ${params.task_gid}). Fix and retry, or drop the html flag to post as plain text:\n- ${problems.join("\n- ")}`,
);
}
}
const imagePaths = params.images ?? [];
if (imagePaths.length > 0) {
const problems = await validateImagePaths(imagePaths);
if (problems.length > 0) {
return toToolResult(
`Asana: refused to post comment (task ${params.task_gid}) - image attachment problem(s):\n- ${problems.join("\n- ")}`,
);
}
}
// Review-before-post gate. The editable path lets the user trim the
// model's prose; Esc cancels the whole write. We also resolve the task
// once up front so the confirm title AND the success summary can show a
// clickable task URL. resolveTasks only fires when a prompt will actually
// be shown (gate on + interactive UI); the headless / gate-off fast path
// defers the lookup to after a successful post.
let resolved: Map | undefined;
let title = `Post comment to task ${params.task_gid}?`;
if (willPromptForWrite(ctx)) {
resolved = await resolveTasks([params.task_gid]);
title = `Post comment to ${fmtTask(params.task_gid, resolved.get(params.task_gid))}?`;
}
const decision = await confirmWrite(ctx, {
title,
editableText: params.text,
summary:
params.text +
(imagePaths.length > 0
? `\n\n[attach: ${imagePaths.map((p) => p.split("/").pop()).join(", ")}]`
: ""),
});
if (!decision.proceed) {
return toToolResult(
`Asana: comment cancelled by user (task ${params.task_gid}). Nothing was posted.`,
);
}
const text = decision.text ?? params.text;
try {
// Upload images BEFORE composing the story: each attachment returns the
// gid the inline ![]()
tag needs. On a mid-batch failure the already-
// attached files stay on the task (Asana binds attachments at upload
// time, unlike Slack), so the error names exactly what landed and what
// was skipped - the comment itself is never half-posted.
let attached: Array<{ gid: string; filename: string }> = [];
if (imagePaths.length > 0) {
attached = [];
for (let i = 0; i < imagePaths.length; i++) {
const file = await readImage(imagePaths[i]);
try {
const record = await callAsanaUpload<{ gid?: string; name?: string }>(
"/attachments",
file,
{ parent: params.task_gid },
);
if (!record?.gid) {
throw new AsanaError(
`Asana: /attachments returned no gid for ${file.filename}.`,
);
}
attached.push({ gid: record.gid, filename: file.filename });
} catch (err) {
const landed =
attached.length > 0
? ` Already attached (kept on the task): ${attached.map((a) => a.filename).join(", ")}.`
: "";
const detail = err instanceof Error ? err.message : String(err);
return toToolResult(
`Asana: failed uploading image ${i + 1}/${imagePaths.length} (${file.filename}) to task ${params.task_gid}: ${detail}.${landed} Comment NOT posted.`,
);
}
}
}
// With images, the story MUST be html_text (the ![]()
tags are the
// inline-embed mechanism), so buildStoryHtml composes the body in both
// modes. Without images the original text-vs-html_text choice applies.
const body: Record =
attached.length > 0
? { html_text: buildStoryHtml({ text, html: params.html === true, images: attached }) }
: params.html
? { html_text: text }
: { text };
const story = await callAsana(
"POST",
`/tasks/${encodeURIComponent(params.task_gid)}/stories`,
{
query: { opt_fields: "gid,text,resource_type,created_at" },
body,
},
);
// Best-effort task permalink so the agent can cite a clickable URL in
// its recap. Reuse the pre-prompt resolve when present; otherwise fetch
// once. resolveTasks swallows per-GID failures, so a miss just omits the
// URL rather than failing an otherwise-successful post.
let permalink = resolved?.get(params.task_gid)?.permalink_url;
if (!permalink) {
permalink = (await resolveTasks([params.task_gid])).get(
params.task_gid,
)?.permalink_url;
}
const urlPart = permalink ? ` URL: ${permalink}` : "";
const imagePart =
attached.length > 0
? ` Attached ${attached.length} image(s): ${attached.map((a) => a.filename).join(", ")} (inline on the comment + in the task's Files).`
: "";
const { extraText, details } = postedContentExtras(text, decision.edited ?? false);
return toToolResult(
`Asana: comment added to task ${params.task_gid} (story gid: ${story.gid}, at ${
story.created_at ?? "(no timestamp)"
}).${urlPart}${imagePart}${extraText}`,
details,
);
} catch (err) {
if (err instanceof AsanaError && err.status === 404) {
return toToolResult(
`Asana: task ${params.task_gid} not found. Verify the GID with \`asana_search_objects\` (resource_type=task).`,
);
}
return toToolResult(errorText(err));
}
},
};
. For multi-paragraph prose, drop the html flag and send plain text with real newlines.`, ); } return problems; } export const addCommentTool: ToolDefinition