agentrace 0.0.11 → 0.1.0

package/dist/commands/mcp-server.js

@@ -47,6 +47,19 @@ const SetPlanStatusSchema = z.object({
     status: z.enum(["scratch", "draft", "planning", "pending", "ready", "implementation", "complete"]).describe("New status for the plan"),
     message: z.string().optional().describe("One-line description of why the status is being changed"),
 });
+const GetPlanCommentsSchema = z.object({
+    plan_id: z.string().describe("Plan document ID"),
+    status: z.enum(["active", "resolved", "outdated", "all"]).optional().describe("Filter comments by status. Defaults to showing all comments."),
+});
+const AddPlanCommentSchema = z.object({
+    plan_id: z.string().describe("Plan document ID"),
+    target_text: z.string().describe("The text in the plan body that this comment refers to"),
+    content: z.string().describe("The comment content"),
+});
+const ResolvePlanCommentSchema = z.object({
+    plan_id: z.string().describe("Plan document ID"),
+    thread_id: z.string().describe("Comment thread ID to resolve"),
+});
 // Tool descriptions with usage guidance
 const TOOL_DESCRIPTIONS = {
     search_plans: `Search plan documents with filtering options.
@@ -62,7 +75,14 @@ WHEN TO USE:
 WHEN TO USE:
 - When the user asks you to check or review a specific plan by ID
 - When you need to understand an existing plan before making changes
-- When the user references a plan ID in their request`,
+- When the user references a plan ID in their request
+
+IMPORTANT - HANDLING COMMENTS:
+- The response includes 'active_comments_count' showing how many unresolved comments exist
+- If the plan is in 'planning' status AND has active comments (active_comments_count > 0):
+  - You SHOULD use get_plan_comments to read the comments
+  - Consider the feedback in the comments and reflect it in your plan updates
+  - Comments represent team feedback that should be addressed before moving to ready`,
     create_plan: `Create a new plan document to record implementation or design plans.
 
 WHEN TO USE:
@@ -108,6 +128,30 @@ STATUS TRANSITION GUIDELINES:
 
 CAUTION:
 - When a plan is in "implementation" status, someone else might already be working on it. Check with the team before starting work on such plans.`,
+    get_plan_comments: `Get comments for a plan document.
+
+WHEN TO USE:
+- When you need to see feedback or discussions on a specific plan
+- When reviewing a plan that others have commented on
+- Before making changes to understand any concerns or suggestions
+
+Returns comments with their status (active, resolved, or outdated).`,
+    add_plan_comment: `Add a comment to a specific location in a plan.
+
+WHEN TO USE:
+- When you want to provide feedback on a specific part of a plan
+- When you have a question or suggestion about the plan content
+- When reviewing a plan and want to leave notes for the team
+
+The comment is anchored to specific text in the plan body.`,
+    resolve_plan_comment: `Resolve a comment thread on a plan.
+
+WHEN TO USE:
+- When you have addressed the feedback in a comment
+- When the issue raised in the comment has been fixed
+- When the comment is no longer relevant after plan updates
+
+Resolving a comment marks it as handled, keeping it visible but indicating it's been addressed.`,
 };
 export async function mcpServerCommand() {
     const server = new McpServer({
@@ -154,6 +198,7 @@ IMPORTANT GUIDELINES:
                 id: plan.id,
                 description: plan.description,
                 status: plan.status,
+                active_comments_count: plan.active_comments_count,
                 git_remote_url: plan.project?.canonical_git_repository || null,
                 url: plan.url || null,
                 updated_at: plan.updated_at,
@@ -184,10 +229,14 @@ IMPORTANT GUIDELINES:
     server.tool("read_plan", TOOL_DESCRIPTIONS.read_plan, ReadPlanSchema.shape, async (args) => {
         try {
             const plan = await getClient().getPlan(args.id);
-            let text = `# ${plan.description}\n\nStatus: ${plan.status}\n\n${plan.body}`;
+            let text = `# ${plan.description}\n\nStatus: ${plan.status}\nActive Comments: ${plan.active_comments_count}\n\n${plan.body}`;
             if (plan.url) {
                 text += `\n\n---\nURL: ${plan.url}`;
             }
+            // Add reminder if there are active comments on a planning status plan
+            if (plan.status === "planning" && plan.active_comments_count > 0) {
+                text += `\n\n---\n⚠️ This plan has ${plan.active_comments_count} active comment(s). Use get_plan_comments to review them and consider the feedback.`;
+            }
             return {
                 content: [
                     {
@@ -316,6 +365,115 @@ IMPORTANT GUIDELINES:
             };
         }
     });
+    // get_plan_comments tool
+    server.tool("get_plan_comments", TOOL_DESCRIPTIONS.get_plan_comments, GetPlanCommentsSchema.shape, async (args) => {
+        try {
+            const threads = await getClient().getThreads(args.plan_id, args.status);
+            if (threads.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "No comments found for this plan.",
+                        },
+                    ],
+                };
+            }
+            const threadList = threads.map((thread) => ({
+                id: thread.id,
+                target_text: thread.target_text,
+                status: thread.status,
+                position: thread.position ? {
+                    start_line: thread.position.start_line,
+                    start_column: thread.position.start_column,
+                    end_line: thread.position.end_line,
+                    end_column: thread.position.end_column,
+                    found: thread.position.found,
+                } : null,
+                messages: thread.messages.map((msg) => ({
+                    id: msg.id,
+                    user_name: msg.user_name,
+                    content: msg.content,
+                    created_at: msg.created_at,
+                })),
+                created_at: thread.created_at,
+            }));
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(threadList, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // add_plan_comment tool
+    server.tool("add_plan_comment", TOOL_DESCRIPTIONS.add_plan_comment, AddPlanCommentSchema.shape, async (args) => {
+        try {
+            const thread = await getClient().createThread(args.plan_id, {
+                target_text: args.target_text,
+                context_before: "",
+                context_after: "",
+                content: args.content,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Comment added successfully.\n\nThread ID: ${thread.id}\nStatus: ${thread.status}\nTarget: "${thread.target_text}"`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // resolve_plan_comment tool
+    server.tool("resolve_plan_comment", TOOL_DESCRIPTIONS.resolve_plan_comment, ResolvePlanCommentSchema.shape, async (args) => {
+        try {
+            const thread = await getClient().resolveThread(args.plan_id, args.thread_id);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Comment resolved successfully.\n\nThread ID: ${thread.id}\nStatus: ${thread.status}\nTarget: "${thread.target_text}"`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
     // Start the server with stdio transport
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/mcp/plan-document-client.d.ts

@@ -16,6 +16,7 @@ export interface PlanDocument {
     url?: string;
     created_at: string;
     updated_at: string;
+    active_comments_count: number;
 }
 export interface PlanDocumentEvent {
     id: string;
@@ -53,6 +54,47 @@ export interface UpdatePlanRequest {
     claude_session_id?: string;
     tool_use_id?: string;
 }
+export type PlanCommentThreadStatus = "active" | "resolved" | "outdated";
+export interface CommentPosition {
+    start_offset: number;
+    end_offset: number;
+    start_line: number;
+    start_column: number;
+    end_line: number;
+    end_column: number;
+    found: boolean;
+}
+export interface PlanCommentMessage {
+    id: string;
+    thread_id: string;
+    user_id: string;
+    user_name: string;
+    content: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface PlanCommentThread {
+    id: string;
+    plan_document_id: string;
+    target_text: string;
+    status: PlanCommentThreadStatus;
+    position: CommentPosition | null;
+    messages: PlanCommentMessage[];
+    created_at: string;
+    updated_at: string;
+}
+export interface ListThreadsResponse {
+    threads: PlanCommentThread[];
+}
+export interface CreateThreadRequest {
+    target_text: string;
+    context_before: string;
+    context_after: string;
+    content: string;
+}
+export interface AddMessageRequest {
+    content: string;
+}
 export declare class PlanDocumentClient {
     private serverUrl;
     private apiKey;
@@ -65,4 +107,8 @@ export declare class PlanDocumentClient {
     updatePlan(id: string, req: UpdatePlanRequest): Promise<PlanDocument>;
     deletePlan(id: string): Promise<void>;
     setStatus(id: string, status: PlanDocumentStatus, message?: string): Promise<PlanDocument>;
+    getThreads(planId: string, status?: PlanCommentThreadStatus | "all"): Promise<PlanCommentThread[]>;
+    createThread(planId: string, req: CreateThreadRequest): Promise<PlanCommentThread>;
+    resolveThread(planId: string, threadId: string): Promise<PlanCommentThread>;
+    addMessage(planId: string, threadId: string, req: AddMessageRequest): Promise<PlanCommentMessage>;
 }

package/dist/mcp/plan-document-client.js

@@ -69,4 +69,24 @@ export class PlanDocumentClient {
     async setStatus(id, status, message) {
         return this.request("PATCH", `/api/plans/${id}/status`, { status, message });
     }
+    // Comment Thread methods
+    async getThreads(planId, status) {
+        const params = new URLSearchParams();
+        if (status) {
+            params.set("status", status);
+        }
+        const query = params.toString();
+        const path = `/api/plans/${planId}/comments${query ? `?${query}` : ""}`;
+        const response = await this.request("GET", path);
+        return response.threads;
+    }
+    async createThread(planId, req) {
+        return this.request("POST", `/api/plans/${planId}/comments`, req);
+    }
+    async resolveThread(planId, threadId) {
+        return this.request("POST", `/api/plans/${planId}/comments/${threadId}/resolve`);
+    }
+    async addMessage(planId, threadId, req) {
+        return this.request("POST", `/api/plans/${planId}/comments/${threadId}/messages`, req);
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentrace",
-  "version": "0.0.11",
+  "version": "0.1.0",
   "description": "CLI for AgenTrace - Claude Code session tracker",
   "type": "module",
   "bin": {