agentrace 0.0.4 → 0.0.6

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,20 +6,23 @@ 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 SearchPlansSchema = z.object({
@@ -37,10 +40,12 @@ 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 = {
@@ -66,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.
 
@@ -88,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:
@@ -106,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
@@ -145,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(", "),
             }));
@@ -197,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: [
@@ -228,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
@@ -238,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: [
@@ -264,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,10 +23,12 @@ export interface PlanDocumentEvent {
     user_id: string | null;
     user_name: string | null;
     patch: string;
+    message: string;
     created_at: string;
 }
 export interface ListPlansResponse {
     plans: PlanDocument[];
+    next_cursor?: string;
 }
 export interface SearchPlansParams {
     gitRemoteUrl?: string;
@@ -40,12 +42,15 @@ 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;
@@ -58,5 +63,5 @@ export declare class PlanDocumentClient {
     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;
@@ -63,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.4",
+  "version": "0.0.6",
   "description": "CLI for AgenTrace - Claude Code session tracker",
   "type": "module",
   "bin": {