@gethmy/mcp 2.8.1 → 2.8.2

package/dist/cli.js

@@ -1121,6 +1121,87 @@ function getDisplayLinkType(linkType, direction) {
     return linkType;
   return LINK_TYPE_INVERSES[linkType];
 }
+// ../harmony-shared/dist/commentSerializer.js
+var CONFLICT_INSTRUCTION = "When two comments conflict, prefer the latest created_at, UNLESS a later " + "comment explicitly confirms or restates the earlier finding. Evaluate " + "substance, not just recency. Cite the comment id(s) you relied on.";
+function authorLabel(c) {
+  if (c.author_type === "agent")
+    return "AI agent";
+  return c.author?.full_name || c.author?.email || "teammate";
+}
+function criticalIds(comments) {
+  const keep = new Set;
+  for (const c of comments) {
+    if (c.comment_type === "decision")
+      keep.add(c.id);
+    if (c.supersedes_id) {
+      keep.add(c.id);
+      keep.add(c.supersedes_id);
+    }
+    if (c.confirms_id) {
+      keep.add(c.id);
+      keep.add(c.confirms_id);
+    }
+  }
+  return keep;
+}
+function serializeCommentThread(comments, options = {}) {
+  const { heading = "Conversation", includeInstructions = true, activity = [], maxComments } = options;
+  const visible = comments.filter((c) => !c.deleted_at).slice().sort((a, b) => a.created_at.localeCompare(b.created_at));
+  if (visible.length === 0)
+    return "";
+  const indexById = new Map;
+  visible.forEach((c, i) => {
+    indexById.set(c.id, i + 1);
+  });
+  let rendered = visible;
+  let elidedCount = 0;
+  if (maxComments && visible.length > maxComments) {
+    const keep = criticalIds(visible);
+    const recentThreshold = visible.length - maxComments;
+    rendered = visible.filter((c, i) => i >= recentThreshold || keep.has(c.id));
+    elidedCount = visible.length - rendered.length;
+  }
+  const ref = (id) => {
+    const n = indexById.get(id);
+    return n ? `#${n}` : `#${id.slice(0, 8)}`;
+  };
+  const lines = [];
+  if (elidedCount > 0) {
+    lines.push({
+      at: visible[0]?.created_at ?? "",
+      text: `(${elidedCount} earlier comment(s) omitted for brevity)`
+    });
+  }
+  for (const c of rendered) {
+    const tags = [];
+    if (c.edited_at)
+      tags.push("edited");
+    if (c.supersedes_id)
+      tags.push(`supersedes ${ref(c.supersedes_id)}`);
+    if (c.confirms_id)
+      tags.push(`confirms ${ref(c.confirms_id)}`);
+    if (c.resolved_at)
+      tags.push("resolved");
+    const tagStr = tags.length ? ` | ${tags.join(" | ")}` : "";
+    const header = `[${ref(c.id)} | ${c.author_type} | ${authorLabel(c)} | ${c.comment_type} | ${c.created_at}${tagStr}]`;
+    lines.push({ at: c.created_at, text: `${header}
+${c.body.trim()}` });
+  }
+  for (const a of activity) {
+    const actor = a.actor ? `${a.actor} ` : "";
+    lines.push({ at: a.at, text: `· (system) ${a.at} — ${actor}${a.text}` });
+  }
+  lines.sort((a, b) => a.at.localeCompare(b.at));
+  const body = lines.map((l) => l.text).join(`
+
+`);
+  const instruction = includeInstructions ? `
+
+${CONFLICT_INSTRUCTION}` : "";
+  return `## ${heading} (oldest → newest)
+
+${body}${instruction}`;
+}
 // ../harmony-shared/dist/constants.js
 var TIMINGS = {
   SEARCH_DEBOUNCE: 300,
@@ -1473,6 +1554,28 @@ class HarmonyApiClient {
   async deleteSubtask(subtaskId) {
     return this.request("DELETE", `/subtasks/${subtaskId}`);
   }
+  async addComment(cardId, body, opts) {
+    return this.request("POST", `/cards/${cardId}/comments`, {
+      body,
+      authorType: "agent",
+      commentType: opts?.commentType,
+      supersedesId: opts?.supersedesId,
+      confirmsId: opts?.confirmsId,
+      agentSessionId: opts?.agentSessionId
+    });
+  }
+  async getComments(cardId, opts) {
+    const qs = new URLSearchParams;
+    if (opts?.limit != null)
+      qs.set("limit", String(opts.limit));
+    if (opts?.offset != null)
+      qs.set("offset", String(opts.offset));
+    const suffix = qs.toString() ? `?${qs.toString()}` : "";
+    return this.request("GET", `/cards/${cardId}/comments${suffix}`);
+  }
+  async updateComment(commentId, updates) {
+    return this.request("PATCH", `/comments/${commentId}`, updates);
+  }
   async startAgentSession(cardId, data) {
     return this.request("POST", `/cards/${cardId}/agent-context`, data);
   }
@@ -1830,6 +1933,24 @@ class HarmonyApiClient {
       assembledContext: assembledContextStr,
       assemblyId
     });
+    try {
+      const { comments } = await this.getComments(options.cardId, {
+        limit: 200
+      });
+      if (Array.isArray(comments) && comments.length > 0) {
+        const section = serializeCommentThread(comments, {
+          heading: "Comments",
+          maxComments: 40
+        });
+        if (section)
+          result.prompt = `${result.prompt}
+
+${section}`;
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.debug(`[generateCardPrompt] comments fetch failed: ${msg}`);
+    }
     try {
       await this.recordPromptHistory({
         cardId: cardData.id,
@@ -3132,6 +3253,66 @@ var TOOLS = {
       required: ["subtaskId"]
     }
   },
+  harmony_add_comment: {
+    description: "Post a comment on a card as the agent. Use this to converse with the human in the open: report progress, ask a question, record a decision, or note a finding — instead of editing the card description. Set supersedesId to correct an earlier comment, confirmsId to reaffirm one. When the thread conflicts, prefer the latest comment unless a later one confirms an earlier finding; cite the comment id(s) you relied on.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cardId: { type: "string", description: "Card UUID to comment on" },
+        body: { type: "string", description: "Comment body (Markdown)" },
+        commentType: {
+          type: "string",
+          enum: [
+            "message",
+            "progress",
+            "question",
+            "blocker",
+            "decision",
+            "summary",
+            "finding"
+          ],
+          description: "Type of comment. 'question'/'blocker' signal you need a human; default 'message'."
+        },
+        supersedesId: {
+          type: "string",
+          description: "Comment id this comment corrects/updates"
+        },
+        confirmsId: {
+          type: "string",
+          description: "Comment id this comment reaffirms"
+        }
+      },
+      required: ["cardId", "body"]
+    }
+  },
+  harmony_get_comments: {
+    description: "Get the comment thread on a card (oldest → newest). Returns human + agent comments with author, type, edited/resolved state, and supersede/confirm links. Read this before acting so you weigh later comments over earlier ones they contradict.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cardId: { type: "string" },
+        limit: { type: "number" },
+        offset: { type: "number" }
+      },
+      required: ["cardId"]
+    }
+  },
+  harmony_update_comment: {
+    description: "Update one of your own comments: edit the body, pin it, or resolve a question/blocker once it has been answered.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        commentId: { type: "string" },
+        body: { type: "string" },
+        pinned: { type: "boolean" },
+        resolve: {
+          type: "boolean",
+          description: "Mark (true) or clear (false) the resolved state"
+        }
+      },
+      required: ["commentId"]
+    }
+  },
   harmony_list_workspaces: {
     description: "List all workspaces the user has access to",
     inputSchema: {
@@ -4393,6 +4574,49 @@ async function handleToolCall(name, args, deps) {
       await client3.deleteSubtask(subtaskId);
       return { success: true };
     }
+    case "harmony_add_comment": {
+      const cardId = z.string().uuid().parse(args.cardId);
+      const body = z.string().min(1).max(1e4).parse(args.body);
+      const commentType = args.commentType !== undefined ? z.enum([
+        "message",
+        "progress",
+        "question",
+        "blocker",
+        "decision",
+        "summary",
+        "finding"
+      ]).parse(args.commentType) : undefined;
+      const supersedesId = args.supersedesId !== undefined ? z.string().uuid().parse(args.supersedesId) : undefined;
+      const confirmsId = args.confirmsId !== undefined ? z.string().uuid().parse(args.confirmsId) : undefined;
+      const result = await client3.addComment(cardId, body, {
+        commentType,
+        supersedesId,
+        confirmsId
+      });
+      return { success: true, ...result };
+    }
+    case "harmony_get_comments": {
+      const cardId = z.string().uuid().parse(args.cardId);
+      const limit = args.limit !== undefined ? z.number().int().min(1).max(500).parse(args.limit) : undefined;
+      const offset = args.offset !== undefined ? z.number().int().min(0).parse(args.offset) : undefined;
+      const result = await client3.getComments(cardId, { limit, offset });
+      return { success: true, ...result };
+    }
+    case "harmony_update_comment": {
+      const commentId = z.string().uuid().parse(args.commentId);
+      const updates = {};
+      if (args.body !== undefined) {
+        updates.body = z.string().min(1).max(1e4).parse(args.body);
+      }
+      if (args.pinned !== undefined) {
+        updates.pinned = z.boolean().parse(args.pinned);
+      }
+      if (args.resolve !== undefined) {
+        updates.resolve = z.boolean().parse(args.resolve);
+      }
+      const result = await client3.updateComment(commentId, updates);
+      return { success: true, ...result };
+    }
     case "harmony_list_workspaces": {
       const result = await client3.listWorkspaces();
       return { success: true, ...result };

package/dist/index.js

@@ -932,6 +932,87 @@ function getDisplayLinkType(linkType, direction) {
     return linkType;
   return LINK_TYPE_INVERSES[linkType];
 }
+// ../harmony-shared/dist/commentSerializer.js
+var CONFLICT_INSTRUCTION = "When two comments conflict, prefer the latest created_at, UNLESS a later " + "comment explicitly confirms or restates the earlier finding. Evaluate " + "substance, not just recency. Cite the comment id(s) you relied on.";
+function authorLabel(c) {
+  if (c.author_type === "agent")
+    return "AI agent";
+  return c.author?.full_name || c.author?.email || "teammate";
+}
+function criticalIds(comments) {
+  const keep = new Set;
+  for (const c of comments) {
+    if (c.comment_type === "decision")
+      keep.add(c.id);
+    if (c.supersedes_id) {
+      keep.add(c.id);
+      keep.add(c.supersedes_id);
+    }
+    if (c.confirms_id) {
+      keep.add(c.id);
+      keep.add(c.confirms_id);
+    }
+  }
+  return keep;
+}
+function serializeCommentThread(comments, options = {}) {
+  const { heading = "Conversation", includeInstructions = true, activity = [], maxComments } = options;
+  const visible = comments.filter((c) => !c.deleted_at).slice().sort((a, b) => a.created_at.localeCompare(b.created_at));
+  if (visible.length === 0)
+    return "";
+  const indexById = new Map;
+  visible.forEach((c, i) => {
+    indexById.set(c.id, i + 1);
+  });
+  let rendered = visible;
+  let elidedCount = 0;
+  if (maxComments && visible.length > maxComments) {
+    const keep = criticalIds(visible);
+    const recentThreshold = visible.length - maxComments;
+    rendered = visible.filter((c, i) => i >= recentThreshold || keep.has(c.id));
+    elidedCount = visible.length - rendered.length;
+  }
+  const ref = (id) => {
+    const n = indexById.get(id);
+    return n ? `#${n}` : `#${id.slice(0, 8)}`;
+  };
+  const lines = [];
+  if (elidedCount > 0) {
+    lines.push({
+      at: visible[0]?.created_at ?? "",
+      text: `(${elidedCount} earlier comment(s) omitted for brevity)`
+    });
+  }
+  for (const c of rendered) {
+    const tags = [];
+    if (c.edited_at)
+      tags.push("edited");
+    if (c.supersedes_id)
+      tags.push(`supersedes ${ref(c.supersedes_id)}`);
+    if (c.confirms_id)
+      tags.push(`confirms ${ref(c.confirms_id)}`);
+    if (c.resolved_at)
+      tags.push("resolved");
+    const tagStr = tags.length ? ` | ${tags.join(" | ")}` : "";
+    const header = `[${ref(c.id)} | ${c.author_type} | ${authorLabel(c)} | ${c.comment_type} | ${c.created_at}${tagStr}]`;
+    lines.push({ at: c.created_at, text: `${header}
+${c.body.trim()}` });
+  }
+  for (const a of activity) {
+    const actor = a.actor ? `${a.actor} ` : "";
+    lines.push({ at: a.at, text: `· (system) ${a.at} — ${actor}${a.text}` });
+  }
+  lines.sort((a, b) => a.at.localeCompare(b.at));
+  const body = lines.map((l) => l.text).join(`
+
+`);
+  const instruction = includeInstructions ? `
+
+${CONFLICT_INSTRUCTION}` : "";
+  return `## ${heading} (oldest → newest)
+
+${body}${instruction}`;
+}
 // ../harmony-shared/dist/constants.js
 var TIMINGS = {
   SEARCH_DEBOUNCE: 300,
@@ -1469,6 +1550,28 @@ class HarmonyApiClient {
   async deleteSubtask(subtaskId) {
     return this.request("DELETE", `/subtasks/${subtaskId}`);
   }
+  async addComment(cardId, body, opts) {
+    return this.request("POST", `/cards/${cardId}/comments`, {
+      body,
+      authorType: "agent",
+      commentType: opts?.commentType,
+      supersedesId: opts?.supersedesId,
+      confirmsId: opts?.confirmsId,
+      agentSessionId: opts?.agentSessionId
+    });
+  }
+  async getComments(cardId, opts) {
+    const qs = new URLSearchParams;
+    if (opts?.limit != null)
+      qs.set("limit", String(opts.limit));
+    if (opts?.offset != null)
+      qs.set("offset", String(opts.offset));
+    const suffix = qs.toString() ? `?${qs.toString()}` : "";
+    return this.request("GET", `/cards/${cardId}/comments${suffix}`);
+  }
+  async updateComment(commentId, updates) {
+    return this.request("PATCH", `/comments/${commentId}`, updates);
+  }
   async startAgentSession(cardId, data) {
     return this.request("POST", `/cards/${cardId}/agent-context`, data);
   }
@@ -1826,6 +1929,24 @@ class HarmonyApiClient {
       assembledContext: assembledContextStr,
       assemblyId
     });
+    try {
+      const { comments } = await this.getComments(options.cardId, {
+        limit: 200
+      });
+      if (Array.isArray(comments) && comments.length > 0) {
+        const section = serializeCommentThread(comments, {
+          heading: "Comments",
+          maxComments: 40
+        });
+        if (section)
+          result.prompt = `${result.prompt}
+
+${section}`;
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.debug(`[generateCardPrompt] comments fetch failed: ${msg}`);
+    }
     try {
       await this.recordPromptHistory({
         cardId: cardData.id,
@@ -3128,6 +3249,66 @@ var TOOLS = {
       required: ["subtaskId"]
     }
   },
+  harmony_add_comment: {
+    description: "Post a comment on a card as the agent. Use this to converse with the human in the open: report progress, ask a question, record a decision, or note a finding — instead of editing the card description. Set supersedesId to correct an earlier comment, confirmsId to reaffirm one. When the thread conflicts, prefer the latest comment unless a later one confirms an earlier finding; cite the comment id(s) you relied on.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cardId: { type: "string", description: "Card UUID to comment on" },
+        body: { type: "string", description: "Comment body (Markdown)" },
+        commentType: {
+          type: "string",
+          enum: [
+            "message",
+            "progress",
+            "question",
+            "blocker",
+            "decision",
+            "summary",
+            "finding"
+          ],
+          description: "Type of comment. 'question'/'blocker' signal you need a human; default 'message'."
+        },
+        supersedesId: {
+          type: "string",
+          description: "Comment id this comment corrects/updates"
+        },
+        confirmsId: {
+          type: "string",
+          description: "Comment id this comment reaffirms"
+        }
+      },
+      required: ["cardId", "body"]
+    }
+  },
+  harmony_get_comments: {
+    description: "Get the comment thread on a card (oldest → newest). Returns human + agent comments with author, type, edited/resolved state, and supersede/confirm links. Read this before acting so you weigh later comments over earlier ones they contradict.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cardId: { type: "string" },
+        limit: { type: "number" },
+        offset: { type: "number" }
+      },
+      required: ["cardId"]
+    }
+  },
+  harmony_update_comment: {
+    description: "Update one of your own comments: edit the body, pin it, or resolve a question/blocker once it has been answered.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        commentId: { type: "string" },
+        body: { type: "string" },
+        pinned: { type: "boolean" },
+        resolve: {
+          type: "boolean",
+          description: "Mark (true) or clear (false) the resolved state"
+        }
+      },
+      required: ["commentId"]
+    }
+  },
   harmony_list_workspaces: {
     description: "List all workspaces the user has access to",
     inputSchema: {
@@ -4389,6 +4570,49 @@ async function handleToolCall(name, args, deps) {
       await client3.deleteSubtask(subtaskId);
       return { success: true };
     }
+    case "harmony_add_comment": {
+      const cardId = z.string().uuid().parse(args.cardId);
+      const body = z.string().min(1).max(1e4).parse(args.body);
+      const commentType = args.commentType !== undefined ? z.enum([
+        "message",
+        "progress",
+        "question",
+        "blocker",
+        "decision",
+        "summary",
+        "finding"
+      ]).parse(args.commentType) : undefined;
+      const supersedesId = args.supersedesId !== undefined ? z.string().uuid().parse(args.supersedesId) : undefined;
+      const confirmsId = args.confirmsId !== undefined ? z.string().uuid().parse(args.confirmsId) : undefined;
+      const result = await client3.addComment(cardId, body, {
+        commentType,
+        supersedesId,
+        confirmsId
+      });
+      return { success: true, ...result };
+    }
+    case "harmony_get_comments": {
+      const cardId = z.string().uuid().parse(args.cardId);
+      const limit = args.limit !== undefined ? z.number().int().min(1).max(500).parse(args.limit) : undefined;
+      const offset = args.offset !== undefined ? z.number().int().min(0).parse(args.offset) : undefined;
+      const result = await client3.getComments(cardId, { limit, offset });
+      return { success: true, ...result };
+    }
+    case "harmony_update_comment": {
+      const commentId = z.string().uuid().parse(args.commentId);
+      const updates = {};
+      if (args.body !== undefined) {
+        updates.body = z.string().min(1).max(1e4).parse(args.body);
+      }
+      if (args.pinned !== undefined) {
+        updates.pinned = z.boolean().parse(args.pinned);
+      }
+      if (args.resolve !== undefined) {
+        updates.resolve = z.boolean().parse(args.resolve);
+      }
+      const result = await client3.updateComment(commentId, updates);
+      return { success: true, ...result };
+    }
     case "harmony_list_workspaces": {
       const result = await client3.listWorkspaces();
       return { success: true, ...result };

package/dist/lib/api-client.js

@@ -724,6 +724,87 @@ function getDisplayLinkType(linkType, direction) {
     return linkType;
   return LINK_TYPE_INVERSES[linkType];
 }
+// ../harmony-shared/dist/commentSerializer.js
+var CONFLICT_INSTRUCTION = "When two comments conflict, prefer the latest created_at, UNLESS a later " + "comment explicitly confirms or restates the earlier finding. Evaluate " + "substance, not just recency. Cite the comment id(s) you relied on.";
+function authorLabel(c) {
+  if (c.author_type === "agent")
+    return "AI agent";
+  return c.author?.full_name || c.author?.email || "teammate";
+}
+function criticalIds(comments) {
+  const keep = new Set;
+  for (const c of comments) {
+    if (c.comment_type === "decision")
+      keep.add(c.id);
+    if (c.supersedes_id) {
+      keep.add(c.id);
+      keep.add(c.supersedes_id);
+    }
+    if (c.confirms_id) {
+      keep.add(c.id);
+      keep.add(c.confirms_id);
+    }
+  }
+  return keep;
+}
+function serializeCommentThread(comments, options = {}) {
+  const { heading = "Conversation", includeInstructions = true, activity = [], maxComments } = options;
+  const visible = comments.filter((c) => !c.deleted_at).slice().sort((a, b) => a.created_at.localeCompare(b.created_at));
+  if (visible.length === 0)
+    return "";
+  const indexById = new Map;
+  visible.forEach((c, i) => {
+    indexById.set(c.id, i + 1);
+  });
+  let rendered = visible;
+  let elidedCount = 0;
+  if (maxComments && visible.length > maxComments) {
+    const keep = criticalIds(visible);
+    const recentThreshold = visible.length - maxComments;
+    rendered = visible.filter((c, i) => i >= recentThreshold || keep.has(c.id));
+    elidedCount = visible.length - rendered.length;
+  }
+  const ref = (id) => {
+    const n = indexById.get(id);
+    return n ? `#${n}` : `#${id.slice(0, 8)}`;
+  };
+  const lines = [];
+  if (elidedCount > 0) {
+    lines.push({
+      at: visible[0]?.created_at ?? "",
+      text: `(${elidedCount} earlier comment(s) omitted for brevity)`
+    });
+  }
+  for (const c of rendered) {
+    const tags = [];
+    if (c.edited_at)
+      tags.push("edited");
+    if (c.supersedes_id)
+      tags.push(`supersedes ${ref(c.supersedes_id)}`);
+    if (c.confirms_id)
+      tags.push(`confirms ${ref(c.confirms_id)}`);
+    if (c.resolved_at)
+      tags.push("resolved");
+    const tagStr = tags.length ? ` | ${tags.join(" | ")}` : "";
+    const header = `[${ref(c.id)} | ${c.author_type} | ${authorLabel(c)} | ${c.comment_type} | ${c.created_at}${tagStr}]`;
+    lines.push({ at: c.created_at, text: `${header}
+${c.body.trim()}` });
+  }
+  for (const a of activity) {
+    const actor = a.actor ? `${a.actor} ` : "";
+    lines.push({ at: a.at, text: `· (system) ${a.at} — ${actor}${a.text}` });
+  }
+  lines.sort((a, b) => a.at.localeCompare(b.at));
+  const body = lines.map((l) => l.text).join(`
+
+`);
+  const instruction = includeInstructions ? `
+
+${CONFLICT_INSTRUCTION}` : "";
+  return `## ${heading} (oldest → newest)
+
+${body}${instruction}`;
+}
 // ../harmony-shared/dist/constants.js
 var TIMINGS = {
   SEARCH_DEBOUNCE: 300,
@@ -1076,6 +1157,28 @@ class HarmonyApiClient {
   async deleteSubtask(subtaskId) {
     return this.request("DELETE", `/subtasks/${subtaskId}`);
   }
+  async addComment(cardId, body, opts) {
+    return this.request("POST", `/cards/${cardId}/comments`, {
+      body,
+      authorType: "agent",
+      commentType: opts?.commentType,
+      supersedesId: opts?.supersedesId,
+      confirmsId: opts?.confirmsId,
+      agentSessionId: opts?.agentSessionId
+    });
+  }
+  async getComments(cardId, opts) {
+    const qs = new URLSearchParams;
+    if (opts?.limit != null)
+      qs.set("limit", String(opts.limit));
+    if (opts?.offset != null)
+      qs.set("offset", String(opts.offset));
+    const suffix = qs.toString() ? `?${qs.toString()}` : "";
+    return this.request("GET", `/cards/${cardId}/comments${suffix}`);
+  }
+  async updateComment(commentId, updates) {
+    return this.request("PATCH", `/comments/${commentId}`, updates);
+  }
   async startAgentSession(cardId, data) {
     return this.request("POST", `/cards/${cardId}/agent-context`, data);
   }
@@ -1433,6 +1536,24 @@ class HarmonyApiClient {
       assembledContext: assembledContextStr,
       assemblyId
     });
+    try {
+      const { comments } = await this.getComments(options.cardId, {
+        limit: 200
+      });
+      if (Array.isArray(comments) && comments.length > 0) {
+        const section = serializeCommentThread(comments, {
+          heading: "Comments",
+          maxComments: 40
+        });
+        if (section)
+          result.prompt = `${result.prompt}
+
+${section}`;
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.debug(`[generateCardPrompt] comments fetch failed: ${msg}`);
+    }
     try {
       await this.recordPromptHistory({
         cardId: cardData.id,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/mcp",
-  "version": "2.8.1",
+  "version": "2.8.2",
   "description": "MCP server for Harmony Kanban board - enables AI coding agents to manage your boards",
   "publishConfig": {
     "access": "public"

package/src/api-client.ts

@@ -1,4 +1,8 @@
-import { getDisplayLinkType } from "@harmony/shared";
+import {
+  type Comment,
+  getDisplayLinkType,
+  serializeCommentThread,
+} from "@harmony/shared";
 import { getApiKey, getApiUrl } from "./config.js";
 
 export interface ApiResponse<T = unknown> {
@@ -617,6 +621,46 @@ export class HarmonyApiClient {
     return this.request("DELETE", `/subtasks/${subtaskId}`);
   }
 
+  // ============ COMMENT OPERATIONS ============
+
+  async addComment(
+    cardId: string,
+    body: string,
+    opts?: {
+      commentType?: string;
+      supersedesId?: string;
+      confirmsId?: string;
+      agentSessionId?: string;
+    },
+  ): Promise<{ comment: unknown }> {
+    return this.request("POST", `/cards/${cardId}/comments`, {
+      body,
+      authorType: "agent",
+      commentType: opts?.commentType,
+      supersedesId: opts?.supersedesId,
+      confirmsId: opts?.confirmsId,
+      agentSessionId: opts?.agentSessionId,
+    });
+  }
+
+  async getComments(
+    cardId: string,
+    opts?: { limit?: number; offset?: number },
+  ): Promise<{ comments: unknown[] }> {
+    const qs = new URLSearchParams();
+    if (opts?.limit != null) qs.set("limit", String(opts.limit));
+    if (opts?.offset != null) qs.set("offset", String(opts.offset));
+    const suffix = qs.toString() ? `?${qs.toString()}` : "";
+    return this.request("GET", `/cards/${cardId}/comments${suffix}`);
+  }
+
+  async updateComment(
+    commentId: string,
+    updates: { body?: string; pinned?: boolean; resolve?: boolean },
+  ): Promise<{ comment: unknown }> {
+    return this.request("PATCH", `/comments/${commentId}`, updates);
+  }
+
   // ============ AGENT CONTEXT OPERATIONS ============
 
   async startAgentSession(
@@ -1448,6 +1492,26 @@ export class HarmonyApiClient {
       assemblyId,
     });
 
+    // Append the card's comment thread (people + agents). This is the central
+    // injection point: every caller of harmony_generate_prompt (daemon, Claude
+    // Code, in-app builder) gets the recency-ordered thread + conflict rule.
+    // Best-effort — never fail prompt generation on a comments fetch error.
+    try {
+      const { comments } = await this.getComments(options.cardId, {
+        limit: 200,
+      });
+      if (Array.isArray(comments) && comments.length > 0) {
+        const section = serializeCommentThread(comments as Comment[], {
+          heading: "Comments",
+          maxComments: 40,
+        });
+        if (section) result.prompt = `${result.prompt}\n\n${section}`;
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.debug(`[generateCardPrompt] comments fetch failed: ${msg}`);
+    }
+
     // AGP P2: persist a session-linked snapshot. Best-effort — never fail
     // prompt generation just because logging didn't land.
     try {

package/src/server.ts

@@ -636,6 +636,72 @@ export const TOOLS = {
     },
   },
 
+  // Comment operations
+  harmony_add_comment: {
+    description:
+      "Post a comment on a card as the agent. Use this to converse with the human in the open: report progress, ask a question, record a decision, or note a finding — instead of editing the card description. Set supersedesId to correct an earlier comment, confirmsId to reaffirm one. When the thread conflicts, prefer the latest comment unless a later one confirms an earlier finding; cite the comment id(s) you relied on.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cardId: { type: "string", description: "Card UUID to comment on" },
+        body: { type: "string", description: "Comment body (Markdown)" },
+        commentType: {
+          type: "string",
+          enum: [
+            "message",
+            "progress",
+            "question",
+            "blocker",
+            "decision",
+            "summary",
+            "finding",
+          ],
+          description:
+            "Type of comment. 'question'/'blocker' signal you need a human; default 'message'.",
+        },
+        supersedesId: {
+          type: "string",
+          description: "Comment id this comment corrects/updates",
+        },
+        confirmsId: {
+          type: "string",
+          description: "Comment id this comment reaffirms",
+        },
+      },
+      required: ["cardId", "body"],
+    },
+  },
+  harmony_get_comments: {
+    description:
+      "Get the comment thread on a card (oldest → newest). Returns human + agent comments with author, type, edited/resolved state, and supersede/confirm links. Read this before acting so you weigh later comments over earlier ones they contradict.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        cardId: { type: "string" },
+        limit: { type: "number" },
+        offset: { type: "number" },
+      },
+      required: ["cardId"],
+    },
+  },
+  harmony_update_comment: {
+    description:
+      "Update one of your own comments: edit the body, pin it, or resolve a question/blocker once it has been answered.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        commentId: { type: "string" },
+        body: { type: "string" },
+        pinned: { type: "boolean" },
+        resolve: {
+          type: "boolean",
+          description: "Mark (true) or clear (false) the resolved state",
+        },
+      },
+      required: ["commentId"],
+    },
+  },
+
   // Context operations
   harmony_list_workspaces: {
     description: "List all workspaces the user has access to",
@@ -2177,6 +2243,71 @@ async function handleToolCall(
       return { success: true };
     }
 
+    // Comment operations
+    case "harmony_add_comment": {
+      const cardId = z.string().uuid().parse(args.cardId);
+      const body = z.string().min(1).max(10_000).parse(args.body);
+      const commentType =
+        args.commentType !== undefined
+          ? z
+              .enum([
+                "message",
+                "progress",
+                "question",
+                "blocker",
+                "decision",
+                "summary",
+                "finding",
+              ])
+              .parse(args.commentType)
+          : undefined;
+      const supersedesId =
+        args.supersedesId !== undefined
+          ? z.string().uuid().parse(args.supersedesId)
+          : undefined;
+      const confirmsId =
+        args.confirmsId !== undefined
+          ? z.string().uuid().parse(args.confirmsId)
+          : undefined;
+      const result = await client.addComment(cardId, body, {
+        commentType,
+        supersedesId,
+        confirmsId,
+      });
+      return { success: true, ...result };
+    }
+
+    case "harmony_get_comments": {
+      const cardId = z.string().uuid().parse(args.cardId);
+      const limit =
+        args.limit !== undefined
+          ? z.number().int().min(1).max(500).parse(args.limit)
+          : undefined;
+      const offset =
+        args.offset !== undefined
+          ? z.number().int().min(0).parse(args.offset)
+          : undefined;
+      const result = await client.getComments(cardId, { limit, offset });
+      return { success: true, ...result };
+    }
+
+    case "harmony_update_comment": {
+      const commentId = z.string().uuid().parse(args.commentId);
+      const updates: { body?: string; pinned?: boolean; resolve?: boolean } =
+        {};
+      if (args.body !== undefined) {
+        updates.body = z.string().min(1).max(10_000).parse(args.body);
+      }
+      if (args.pinned !== undefined) {
+        updates.pinned = z.boolean().parse(args.pinned);
+      }
+      if (args.resolve !== undefined) {
+        updates.resolve = z.boolean().parse(args.resolve);
+      }
+      const result = await client.updateComment(commentId, updates);
+      return { success: true, ...result };
+    }
+
     // Context operations
     case "harmony_list_workspaces": {
       const result = await client.listWorkspaces();