agentrace 0.0.3 → 0.0.5

package/dist/commands/init.js

@@ -25,7 +25,7 @@ export async function initCommand(options = {}) {
         console.error("Error: Invalid URL format");
         process.exit(1);
     }
-    console.log("Agentrace Setup\n");
+    console.log("AgenTrace Setup\n");
     if (options.dev) {
         console.log("[Dev Mode] Using local CLI for hooks\n");
     }

package/dist/commands/mcp-server.js

@@ -6,24 +6,29 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import * as os from "node:os";
 import { PlanDocumentClient } from "../mcp/plan-document-client.js";
-// Read session_id from file written by PreToolUse hook
-function getSessionIdFromFile() {
+// Read session_id and tool_use_id from file written by PreToolUse hook
+function getSessionInfoFromFile() {
     try {
         const sessionFile = path.join(os.homedir(), ".agentrace", "current-session.json");
         if (fs.existsSync(sessionFile)) {
             const content = fs.readFileSync(sessionFile, "utf-8");
             const data = JSON.parse(content);
-            return data.session_id;
+            return {
+                session_id: data.session_id,
+                tool_use_id: data.tool_use_id,
+            };
         }
     }
     catch {
-        // Ignore errors, return undefined
+        // Ignore errors, return empty object
     }
-    return undefined;
+    return {};
 }
 // Tool schemas
-const ListPlansSchema = z.object({
-    git_remote_url: z.string().describe("Git remote URL to filter plans"),
+const SearchPlansSchema = z.object({
+    git_remote_url: z.string().optional().describe("Git remote URL to filter by project"),
+    status: z.string().optional().describe("Comma-separated statuses to filter (e.g., 'planning,implementation')"),
+    description: z.string().optional().describe("Partial match search on plan description"),
 });
 const ReadPlanSchema = z.object({
     id: z.string().describe("Plan document ID"),
@@ -35,19 +40,23 @@ const CreatePlanSchema = z.object({
 const UpdatePlanSchema = z.object({
     id: z.string().describe("Plan document ID"),
     body: z.string().describe("Updated plan content in Markdown format"),
+    message: z.string().optional().describe("One-line description of what was changed"),
 });
 const SetPlanStatusSchema = z.object({
     id: z.string().describe("Plan document ID"),
-    status: z.enum(["scratch", "draft", "planning", "pending", "implementation", "complete"]).describe("New status for the plan"),
+    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"),
 });
 // Tool descriptions with usage guidance
 const TOOL_DESCRIPTIONS = {
-    list_plans: `List plan documents for a repository.
+    search_plans: `Search plan documents with filtering options.
 
 WHEN TO USE:
 - When you need to check existing plans for the current repository
 - When the user asks about available plans or implementation documents
-- Before creating a new plan to avoid duplicates`,
+- Before creating a new plan to avoid duplicates
+- When searching for plans by status (e.g., find all plans in 'scratch' status)
+- When searching for plans by description keyword`,
     read_plan: `Read a plan document by ID.
 
 WHEN TO USE:
@@ -62,7 +71,7 @@ WHEN TO USE:
 - When the user asks you to save or persist a plan
 - When planning significant features, refactoring, or architectural changes
 
-The plan will be saved to Agentrace server and can be reviewed by the team.
+The plan will be saved to AgenTrace server and can be reviewed by the team.
 The project is automatically determined from the session's git repository.`,
     update_plan: `Update an existing plan document.
 
@@ -84,15 +93,17 @@ Available statuses:
 - draft: Plan not yet fully considered (optional intermediate status)
 - planning: Plan is being designed/refined through discussion
 - pending: Waiting for approval or blocked
+- ready: Plan is finalized and ready for implementation (awaiting review/approval to start)
 - implementation: Active development is in progress
 - complete: The work described in the plan is finished
 
-BASIC FLOW: scratch → planning → implementation → complete
+BASIC FLOW: scratch → planning → ready → implementation → complete
 (draft and pending are optional auxiliary statuses)
 
 STATUS TRANSITION GUIDELINES:
 - scratch → planning: When you read a scratch plan (usually written by human), review its content and rewrite it into a more concrete plan, then change status to planning
-- planning → implementation: When the plan is finalized after discussion, change status to implementation before starting work
+- planning → ready: When the plan is finalized after discussion, change status to ready
+- ready → implementation: When you start working on the plan, change status to implementation
 - implementation → complete: When all work described in the plan is finished, change status to complete
 
 CAUTION:
@@ -102,10 +113,10 @@ export async function mcpServerCommand() {
     const server = new McpServer({
         name: "agentrace",
         version: "1.0.0",
-        description: `Agentrace Plan Document Management Server.
+        description: `AgenTrace Plan Document Management Server.
 
 This server provides tools to manage implementation and design plans.
-Plans are stored on the Agentrace server and can be reviewed by the team.
+Plans are stored on the AgenTrace server and can be reviewed by the team.
 
 IMPORTANT GUIDELINES:
 - When you create a design or implementation plan, ALWAYS save it using create_plan
@@ -119,16 +130,20 @@ IMPORTANT GUIDELINES:
         }
         return client;
     }
-    // list_plans tool
-    server.tool("list_plans", TOOL_DESCRIPTIONS.list_plans, ListPlansSchema.shape, async (args) => {
+    // search_plans tool
+    server.tool("search_plans", TOOL_DESCRIPTIONS.search_plans, SearchPlansSchema.shape, async (args) => {
         try {
-            const plans = await getClient().listPlans(args.git_remote_url);
+            const plans = await getClient().searchPlans({
+                gitRemoteUrl: args.git_remote_url,
+                status: args.status,
+                description: args.description,
+            });
             if (plans.length === 0) {
                 return {
                     content: [
                         {
                             type: "text",
-                            text: "No plans found for this repository.",
+                            text: "No plans found matching the search criteria.",
                         },
                     ],
                 };
@@ -137,6 +152,7 @@ IMPORTANT GUIDELINES:
                 id: plan.id,
                 description: plan.description,
                 status: plan.status,
+                git_remote_url: plan.project?.canonical_git_repository || null,
                 updated_at: plan.updated_at,
                 collaborators: plan.collaborators.map((c) => c.display_name).join(", "),
             }));
@@ -189,12 +205,13 @@ IMPORTANT GUIDELINES:
     // create_plan tool
     server.tool("create_plan", TOOL_DESCRIPTIONS.create_plan, CreatePlanSchema.shape, async (args) => {
         try {
-            // Read session_id from file written by PreToolUse hook
-            const claudeSessionId = getSessionIdFromFile();
+            // Read session_id and tool_use_id from file written by PreToolUse hook
+            const sessionInfo = getSessionInfoFromFile();
             const plan = await getClient().createPlan({
                 description: args.description,
                 body: args.body,
-                claude_session_id: claudeSessionId,
+                claude_session_id: sessionInfo.session_id,
+                tool_use_id: sessionInfo.tool_use_id,
             });
             return {
                 content: [
@@ -220,8 +237,8 @@ IMPORTANT GUIDELINES:
     // update_plan tool
     server.tool("update_plan", TOOL_DESCRIPTIONS.update_plan, UpdatePlanSchema.shape, async (args) => {
         try {
-            // Read session_id from file written by PreToolUse hook
-            const claudeSessionId = getSessionIdFromFile();
+            // Read session_id and tool_use_id from file written by PreToolUse hook
+            const sessionInfo = getSessionInfoFromFile();
             // Get current plan to compute patch
             const currentPlan = await getClient().getPlan(args.id);
             // Compute patch using diff-match-patch
@@ -230,7 +247,9 @@ IMPORTANT GUIDELINES:
             const plan = await getClient().updatePlan(args.id, {
                 body: args.body,
                 patch: patchText,
-                claude_session_id: claudeSessionId,
+                message: args.message,
+                claude_session_id: sessionInfo.session_id,
+                tool_use_id: sessionInfo.tool_use_id,
             });
             return {
                 content: [
@@ -256,7 +275,7 @@ IMPORTANT GUIDELINES:
     // set_plan_status tool
     server.tool("set_plan_status", TOOL_DESCRIPTIONS.set_plan_status, SetPlanStatusSchema.shape, async (args) => {
         try {
-            const plan = await getClient().setStatus(args.id, args.status);
+            const plan = await getClient().setStatus(args.id, args.status, args.message);
             return {
                 content: [
                     {

package/dist/commands/off.js

@@ -4,7 +4,7 @@ export async function offCommand() {
     // Check if config exists
     const config = loadConfig();
     if (!config) {
-        console.log("Agentrace is not configured. Run 'npx agentrace init' first.");
+        console.log("AgenTrace is not configured. Run 'npx agentrace init' first.");
         return;
     }
     const result = uninstallHooks();

package/dist/commands/on.js

@@ -8,7 +8,7 @@ export async function onCommand(options = {}) {
     // Check if config exists
     const config = loadConfig();
     if (!config) {
-        console.log("Agentrace is not configured. Run 'npx agentrace init' first.");
+        console.log("AgenTrace is not configured. Run 'npx agentrace init' first.");
         return;
     }
     // Determine hook command

package/dist/commands/send.d.ts

@@ -1 +1,12 @@
+/**
+ * Hook-based send command.
+ * Reads session info from stdin (provided by Claude Code hooks).
+ */
 export declare function sendCommand(): Promise<void>;
+/**
+ * Manual send command.
+ * Finds session file by ID and sends to server.
+ */
+export declare function sendManualCommand(options: {
+    sessionId: string;
+}): Promise<void>;

package/dist/commands/send.js

@@ -2,6 +2,7 @@ import { execSync } from "child_process";
 import { loadConfig } from "../config/manager.js";
 import { getNewLines, saveCursor, hasCursor } from "../config/cursor.js";
 import { sendIngest } from "../utils/http.js";
+import { findSessionFile, extractCwdFromTranscript, } from "../utils/session-finder.js";
 function getGitRemoteUrl(cwd) {
     try {
         const url = execSync("git remote get-url origin", {
@@ -28,6 +29,78 @@ function getGitBranch(cwd) {
         return null;
     }
 }
+/**
+ * Core logic for sending transcript data to the server.
+ * Shared between hook-based and manual invocations.
+ */
+async function sendTranscript(params) {
+    const { sessionId, transcriptPath, cwd, isHook } = params;
+    const exitWithError = (message) => {
+        console.error(message);
+        process.exit(isHook ? 0 : 1);
+    };
+    // Check if config exists
+    const config = loadConfig();
+    if (!config) {
+        exitWithError("[agentrace] Warning: Config not found. Run 'npx agentrace init' first.");
+        return;
+    }
+    // Get new lines from transcript
+    const { lines, totalLineCount } = getNewLines(transcriptPath, sessionId);
+    if (lines.length === 0) {
+        if (!isHook) {
+            console.log("[agentrace] No new lines to send.");
+        }
+        process.exit(0);
+    }
+    // Parse JSONL lines
+    const transcriptLines = [];
+    for (const line of lines) {
+        try {
+            transcriptLines.push(JSON.parse(line));
+        }
+        catch {
+            // Skip invalid JSON lines
+        }
+    }
+    if (transcriptLines.length === 0) {
+        if (!isHook) {
+            console.log("[agentrace] No valid transcript lines to send.");
+        }
+        process.exit(0);
+    }
+    // Extract git info only on first send (when cursor doesn't exist yet)
+    let gitRemoteUrl;
+    let gitBranch;
+    if (cwd && !hasCursor(sessionId)) {
+        gitRemoteUrl = getGitRemoteUrl(cwd) ?? undefined;
+        gitBranch = getGitBranch(cwd) ?? undefined;
+    }
+    // Send to server
+    const result = await sendIngest({
+        session_id: sessionId,
+        transcript_lines: transcriptLines,
+        cwd: cwd,
+        git_remote_url: gitRemoteUrl,
+        git_branch: gitBranch,
+    });
+    if (result.ok) {
+        // Update cursor on success
+        saveCursor(sessionId, totalLineCount);
+        if (!isHook) {
+            console.log(`[agentrace] Sent ${transcriptLines.length} lines for session ${sessionId}`);
+        }
+    }
+    else {
+        exitWithError(`[agentrace] Warning: ${result.error}`);
+        return;
+    }
+    process.exit(0);
+}
+/**
+ * Hook-based send command.
+ * Reads session info from stdin (provided by Claude Code hooks).
+ */
 export async function sendCommand() {
     // Check if config exists
     const config = loadConfig();
@@ -68,51 +141,43 @@ export async function sendCommand() {
     if (data.hook_event_name === "UserPromptSubmit") {
         await sleep(10000);
     }
-    // Get new lines from transcript
-    const { lines, totalLineCount } = getNewLines(transcriptPath, sessionId);
-    if (lines.length === 0) {
-        // No new lines to send
-        process.exit(0);
-    }
-    // Parse JSONL lines
-    const transcriptLines = [];
-    for (const line of lines) {
-        try {
-            transcriptLines.push(JSON.parse(line));
-        }
-        catch {
-            // Skip invalid JSON lines
-        }
-    }
-    if (transcriptLines.length === 0) {
-        process.exit(0);
-    }
     // Use CLAUDE_PROJECT_DIR (stable project root) instead of cwd (can change during builds)
     const projectDir = process.env.CLAUDE_PROJECT_DIR || data.cwd;
-    // Extract git info only on first send (when cursor doesn't exist yet)
-    let gitRemoteUrl;
-    let gitBranch;
-    if (projectDir && !hasCursor(sessionId)) {
-        gitRemoteUrl = getGitRemoteUrl(projectDir) ?? undefined;
-        gitBranch = getGitBranch(projectDir) ?? undefined;
-    }
-    // Send to server
-    const result = await sendIngest({
-        session_id: sessionId,
-        transcript_lines: transcriptLines,
+    await sendTranscript({
+        sessionId,
+        transcriptPath,
         cwd: projectDir,
-        git_remote_url: gitRemoteUrl,
-        git_branch: gitBranch,
+        isHook: true,
+    });
+}
+/**
+ * Manual send command.
+ * Finds session file by ID and sends to server.
+ */
+export async function sendManualCommand(options) {
+    const { sessionId } = options;
+    // Check if config exists
+    const config = loadConfig();
+    if (!config) {
+        console.error("[agentrace] Error: Config not found. Run 'npx agentrace init' first.");
+        process.exit(1);
+    }
+    // Find session file
+    const transcriptPath = findSessionFile(sessionId);
+    if (!transcriptPath) {
+        console.error(`[agentrace] Error: Session file not found for ID: ${sessionId}`);
+        console.error("  Searched in: ~/.claude/projects/");
+        process.exit(1);
+    }
+    // Extract cwd from transcript
+    const cwd = extractCwdFromTranscript(transcriptPath) ?? undefined;
+    console.log(`[agentrace] Found session file: ${transcriptPath}`);
+    await sendTranscript({
+        sessionId,
+        transcriptPath,
+        cwd,
+        isHook: false,
     });
-    if (result.ok) {
-        // Update cursor on success
-        saveCursor(sessionId, totalLineCount);
-    }
-    else {
-        console.error(`[agentrace] Warning: ${result.error}`);
-    }
-    // Always exit 0 to not block hooks
-    process.exit(0);
 }
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));

package/dist/commands/uninstall.js

@@ -1,7 +1,7 @@
 import { deleteConfig } from "../config/manager.js";
 import { uninstallHooks, uninstallMcpServer, uninstallPreToolUseHook } from "../hooks/installer.js";
 export async function uninstallCommand() {
-    console.log("Uninstalling Agentrace...\n");
+    console.log("Uninstalling AgenTrace...\n");
     // Remove hooks
     const hookResult = uninstallHooks();
     if (hookResult.success) {

package/dist/hooks/installer.js

@@ -236,7 +236,7 @@ export function checkMcpServerInstalled() {
 }
 // PreToolUse hook for injecting session_id into agentrace MCP tools
 const SESSION_ID_HOOK_SCRIPT = `#!/usr/bin/env node
-// Agentrace PreToolUse hook: Writes session_id to file for MCP tools
+// Agentrace PreToolUse hook: Writes session_id and tool_use_id to file for MCP tools
 // This hook is called before agentrace MCP tools (create_plan, update_plan)
 
 const fs = require('fs');
@@ -252,9 +252,10 @@ process.stdin.on('end', () => {
   try {
     const data = JSON.parse(input);
     const sessionId = data.session_id;
+    const toolUseId = data.tool_use_id;
 
-    // Write session_id to file for MCP server to read
-    fs.writeFileSync(sessionFile, JSON.stringify({ session_id: sessionId }));
+    // Write session_id and tool_use_id to file for MCP server to read
+    fs.writeFileSync(sessionFile, JSON.stringify({ session_id: sessionId, tool_use_id: toolUseId }));
 
     // Allow the tool to proceed
     const output = {

package/dist/index.js

@@ -2,13 +2,13 @@
 import { Command } from "commander";
 import { initCommand } from "./commands/init.js";
 import { loginCommand } from "./commands/login.js";
-import { sendCommand } from "./commands/send.js";
+import { sendCommand, sendManualCommand } from "./commands/send.js";
 import { uninstallCommand } from "./commands/uninstall.js";
 import { onCommand } from "./commands/on.js";
 import { offCommand } from "./commands/off.js";
 import { mcpServerCommand } from "./commands/mcp-server.js";
 const program = new Command();
-program.name("agentrace").description("CLI for Agentrace").version("0.1.0");
+program.name("agentrace").description("CLI for AgenTrace").version("0.1.0");
 program
     .command("init")
     .description("Initialize agentrace configuration and hooks")
@@ -25,9 +25,15 @@ program
 });
 program
     .command("send")
-    .description("Send event to server (used by hooks)")
-    .action(async () => {
-    await sendCommand();
+    .description("Send event to server (used by hooks, or manually with --claude-session-id)")
+    .option("--claude-session-id <id>", "Send existing Claude session by ID")
+    .action(async (options) => {
+    if (options.claudeSessionId) {
+        await sendManualCommand({ sessionId: options.claudeSessionId });
+    }
+    else {
+        await sendCommand();
+    }
 });
 program
     .command("uninstall")

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

@@ -1,4 +1,4 @@
-export type PlanDocumentStatus = "scratch" | "draft" | "planning" | "pending" | "implementation" | "complete";
+export type PlanDocumentStatus = "scratch" | "draft" | "planning" | "pending" | "ready" | "implementation" | "complete";
 export interface Project {
     id: string;
     canonical_git_repository: string;
@@ -23,11 +23,17 @@ export interface PlanDocumentEvent {
     user_id: string | null;
     user_name: string | null;
     patch: string;
+    message: string;
     created_at: string;
 }
 export interface ListPlansResponse {
     plans: PlanDocument[];
 }
+export interface SearchPlansParams {
+    gitRemoteUrl?: string;
+    status?: string;
+    description?: string;
+}
 export interface ListEventsResponse {
     events: PlanDocumentEvent[];
 }
@@ -35,23 +41,26 @@ export interface CreatePlanRequest {
     description: string;
     body: string;
     claude_session_id?: string;
+    tool_use_id?: string;
 }
 export interface UpdatePlanRequest {
     description?: string;
     body?: string;
     patch?: string;
+    message?: string;
     claude_session_id?: string;
+    tool_use_id?: string;
 }
 export declare class PlanDocumentClient {
     private serverUrl;
     private apiKey;
     constructor();
     private request;
-    listPlans(gitRemoteUrl?: string): Promise<PlanDocument[]>;
+    searchPlans(params?: SearchPlansParams): Promise<PlanDocument[]>;
     getPlan(id: string): Promise<PlanDocument>;
     getPlanEvents(id: string): Promise<PlanDocumentEvent[]>;
     createPlan(req: CreatePlanRequest): Promise<PlanDocument>;
     updatePlan(id: string, req: UpdatePlanRequest): Promise<PlanDocument>;
     deletePlan(id: string): Promise<void>;
-    setStatus(id: string, status: PlanDocumentStatus): Promise<PlanDocument>;
+    setStatus(id: string, status: PlanDocumentStatus, message?: string): Promise<PlanDocument>;
 }

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

@@ -5,7 +5,7 @@ export class PlanDocumentClient {
     constructor() {
         const config = loadConfig();
         if (!config) {
-            throw new Error("Agentrace is not configured. Run 'npx agentrace init' first.");
+            throw new Error("AgenTrace is not configured. Run 'npx agentrace init' first.");
         }
         this.serverUrl = config.server_url;
         this.apiKey = config.api_key;
@@ -31,11 +31,19 @@ export class PlanDocumentClient {
         }
         return response.json();
     }
-    async listPlans(gitRemoteUrl) {
-        let path = "/api/plans";
-        if (gitRemoteUrl) {
-            path += `?git_remote_url=${encodeURIComponent(gitRemoteUrl)}`;
+    async searchPlans(params = {}) {
+        const searchParams = new URLSearchParams();
+        if (params.gitRemoteUrl) {
+            searchParams.set("git_remote_url", params.gitRemoteUrl);
         }
+        if (params.status) {
+            searchParams.set("status", params.status);
+        }
+        if (params.description) {
+            searchParams.set("description", params.description);
+        }
+        const query = searchParams.toString();
+        const path = query ? `/api/plans?${query}` : "/api/plans";
         const response = await this.request("GET", path);
         return response.plans;
     }
@@ -55,7 +63,7 @@ export class PlanDocumentClient {
     async deletePlan(id) {
         await this.request("DELETE", `/api/plans/${id}`);
     }
-    async setStatus(id, status) {
-        return this.request("PATCH", `/api/plans/${id}/status`, { status });
+    async setStatus(id, status, message) {
+        return this.request("PATCH", `/api/plans/${id}/status`, { status, message });
     }
 }

package/dist/utils/session-finder.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Find a Claude session JSONL file by session ID.
+ * Searches recursively in ~/.claude/projects/
+ */
+export declare function findSessionFile(sessionId: string): string | null;
+/**
+ * Extract the cwd from a transcript JSONL file.
+ * Looks for the first entry with type="user" that has a cwd field.
+ */
+export declare function extractCwdFromTranscript(transcriptPath: string): string | null;

package/dist/utils/session-finder.js

@@ -0,0 +1,66 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+const CLAUDE_PROJECTS_DIR = path.join(os.homedir(), ".claude", "projects");
+/**
+ * Find a Claude session JSONL file by session ID.
+ * Searches recursively in ~/.claude/projects/
+ */
+export function findSessionFile(sessionId) {
+    const targetFileName = `${sessionId}.jsonl`;
+    if (!fs.existsSync(CLAUDE_PROJECTS_DIR)) {
+        return null;
+    }
+    // Recursively search for the session file
+    const result = searchDirectory(CLAUDE_PROJECTS_DIR, targetFileName);
+    return result;
+}
+function searchDirectory(dir, targetFileName) {
+    try {
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                const result = searchDirectory(fullPath, targetFileName);
+                if (result) {
+                    return result;
+                }
+            }
+            else if (entry.isFile() && entry.name === targetFileName) {
+                return fullPath;
+            }
+        }
+    }
+    catch {
+        // Skip directories we can't read
+    }
+    return null;
+}
+/**
+ * Extract the cwd from a transcript JSONL file.
+ * Looks for the first entry with type="user" that has a cwd field.
+ */
+export function extractCwdFromTranscript(transcriptPath) {
+    try {
+        if (!fs.existsSync(transcriptPath)) {
+            return null;
+        }
+        const content = fs.readFileSync(transcriptPath, "utf-8");
+        const lines = content.split("\n").filter((line) => line.trim() !== "");
+        for (const line of lines) {
+            try {
+                const entry = JSON.parse(line);
+                if (entry.type === "user" && entry.cwd) {
+                    return entry.cwd;
+                }
+            }
+            catch {
+                // Skip invalid JSON lines
+            }
+        }
+    }
+    catch {
+        // File read error
+    }
+    return null;
+}

package/package.json

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