@gethmy/agent 1.0.1 → 1.0.3

package/dist/progress-tracker.js

@@ -3,17 +3,40 @@ import { AGENT_NAME, agentIdentifier } from "./types.js";
 const TAG = "progress-tracker";
 const THROTTLE_MS = 5_000;
 const HEARTBEAT_MS = 60_000;
+const MAX_TASK_LENGTH = 120;
+const MAX_RECENT_ACTIONS = 5;
+// Hoisted regexes — avoids recompilation on every call
+const SENTENCE_SPLIT = /\.\s|\n/;
+const ACTION_PREFIX = /^(Let me|I'll|I need to|Now|First|Next|Looking|Checking|Creating|Adding|Updating|Fixing|Refactoring|Moving|The |This )/i;
+const GIT_COMMIT_RE = /\bgit\s+commit\b/;
+const BUILD_CMD_RE = /\b(test|build|lint|check|tsc|vitest|jest|(?:bun|npm|pnpm|yarn) run (?:build|lint))\b/;
 const PHASES = {
-    exploring: { min: 10, max: 25, task: "Reading codebase..." },
-    implementing: { min: 25, max: 55, task: "Implementing changes..." },
-    testing: { min: 55, max: 65, task: "Running tests..." },
-    committing: { min: 65, max: 70, task: "Committing changes..." },
-    finishing: { min: 70, max: 75, task: "Finalizing..." },
+    exploring: { min: 10, max: 25, label: "Exploring" },
+    implementing: { min: 25, max: 55, label: "Implementing" },
+    testing: { min: 55, max: 65, label: "Testing" },
+    committing: { min: 65, max: 70, label: "Committing" },
+    finishing: { min: 70, max: 75, label: "Finalizing" },
+};
+const PHASE_ORDER = {
+    exploring: 0,
+    implementing: 1,
+    testing: 2,
+    committing: 3,
+    finishing: 4,
 };
-// Tools that indicate exploring phase
-const _EXPLORE_TOOLS = new Set(["Read", "Glob", "Grep", "Agent"]);
 // Tools that indicate implementation
 const EDIT_TOOLS = new Set(["Write", "Edit", "MultiEdit", "NotebookEdit"]);
+function truncate(str, max) {
+    return str.length > max ? `${str.slice(0, max - 3)}...` : str;
+}
+// Map file-based tools to their display verbs
+const FILE_TOOL_VERBS = {
+    Read: ["Reading", "file_path"],
+    Edit: ["Editing", "file_path"],
+    MultiEdit: ["Editing", "file_path"],
+    Write: ["Writing", "file_path"],
+    NotebookEdit: ["Editing notebook", "notebook_path"],
+};
 export class ProgressTracker {
     client;
     cardId;
@@ -24,12 +47,20 @@ export class ProgressTracker {
     hasEdited = false;
     lastUpdateAt = 0;
     pendingUpdate = null;
+    pendingTask = "";
     heartbeatTimer = null;
     stopped = false;
+    // Rich task tracking
+    lastAction = "";
     // Subtask tracking
     subtaskTotal;
     subtaskCompleted;
     subtaskMode;
+    // Rich activity tracking
+    filesEdited = new Set();
+    filesRead = new Set();
+    lastCost = null;
+    recentActions = [];
     constructor(client, cardId, workerId, subtasks) {
         this.client = client;
         this.cardId = cardId;
@@ -45,8 +76,14 @@ export class ProgressTracker {
         parser.on("tool_start", (name, input) => {
             this.onToolStart(name, input);
         });
-        parser.on("tool_end", (name) => {
-            this.onToolEnd(name);
+        parser.on("tool_end", (name, _id, content) => {
+            this.onToolEnd(name, content);
+        });
+        parser.on("text", (content) => {
+            this.onText(content);
+        });
+        parser.on("cost_update", (cost) => {
+            this.lastCost = cost;
         });
         this.startHeartbeat();
     }
@@ -64,54 +101,112 @@ export class ProgressTracker {
             this.heartbeatTimer = null;
         }
     }
+    /** Get a summary of the session stats. */
+    get stats() {
+        return {
+            filesEdited: this.filesEdited.size,
+            filesRead: this.filesRead.size,
+            toolCalls: this.toolCallCount,
+            cost: this.lastCost,
+        };
+    }
     onToolStart(name, input) {
         this.toolCallCount++;
         log.debug(TAG, `Tool: ${name} (count: ${this.toolCallCount}, phase: ${this.phase})`);
+        // Track files
+        const filePath = this.extractString(input, "file_path");
+        if (filePath) {
+            if (EDIT_TOOLS.has(name)) {
+                this.filesEdited.add(filePath);
+            }
+            else if (name === "Read" || name === "Glob" || name === "Grep") {
+                this.filesRead.add(filePath);
+            }
+        }
         // Detect phase transitions
         if (!this.hasEdited && EDIT_TOOLS.has(name)) {
             this.hasEdited = true;
             this.transitionTo("implementing");
         }
         else if (this.hasEdited && name === "Bash") {
-            const cmd = this.extractBashCommand(input);
-            if (cmd && /\bgit\s+commit\b/.test(cmd)) {
+            const cmd = this.extractString(input, "command");
+            if (cmd && GIT_COMMIT_RE.test(cmd)) {
                 this.transitionTo("committing");
             }
-            else if (cmd &&
-                /\b(test|build|lint|check|tsc|vitest|jest|(?:bun|npm|pnpm|yarn) run (?:build|lint))\b/.test(cmd)) {
+            else if (cmd && BUILD_CMD_RE.test(cmd)) {
                 this.transitionTo("testing");
             }
         }
-        else if (name.startsWith("mcp__harmony__harmony_end_agent_session")) {
+        else if (name === "mcp__harmony__harmony_end_agent_session") {
             this.transitionTo("finishing");
         }
         // Handle subtask toggling — override heuristic progress
         if (name === "mcp__harmony__harmony_toggle_subtask" && this.subtaskMode) {
-            this.subtaskCompleted = Math.min(this.subtaskCompleted + 1, this.subtaskTotal);
+            const val = this.extractString(input, "completed");
+            const completing = val === null || val === "true";
+            if (completing) {
+                this.subtaskCompleted = Math.min(this.subtaskCompleted + 1, this.subtaskTotal);
+            }
+            else {
+                this.subtaskCompleted = Math.max(this.subtaskCompleted - 1, 0);
+            }
             const subtaskProgress = Math.round(10 + (this.subtaskCompleted / this.subtaskTotal) * 60);
             this.progress = Math.max(this.progress, subtaskProgress);
             this.scheduleUpdate(`Completed subtask ${this.subtaskCompleted}/${this.subtaskTotal}`);
             return;
         }
-        // Increment progress within current phase bounds
+        // Build rich action description and increment progress
+        const action = this.describeToolAction(name, input);
+        if (action) {
+            this.lastAction = action;
+            this.pushRecentAction(action);
+        }
         this.incrementProgress();
     }
-    onToolEnd(_name) {
+    onToolEnd(name, content) {
+        // Detect build/test failures from Bash results
+        if (name === "Bash" && content && this.phase === "testing") {
+            const lower = content.slice(-500).toLowerCase();
+            if (lower.includes("error") &&
+                (lower.includes("build failed") ||
+                    lower.includes("failed to compile") ||
+                    lower.includes("exit code 1"))) {
+                this.lastAction = "Build failed — fixing errors";
+                this.scheduleUpdate(this.lastAction);
+            }
+        }
         // Reset heartbeat on any activity
         this.startHeartbeat();
     }
+    onText(content) {
+        // Capture brief reasoning snippets from Claude's text output.
+        // Only update if the text looks like a meaningful status line
+        // (skip very short fragments from streaming).
+        const trimmed = content.trim();
+        if (trimmed.length < 10)
+            return;
+        // Extract first sentence or line as a brief description
+        const end = trimmed.search(SENTENCE_SPLIT);
+        const firstLine = (end === -1 ? trimmed : trimmed.slice(0, end)).trim();
+        if (firstLine.length >= 10 && firstLine.length <= 200) {
+            if (ACTION_PREFIX.test(firstLine)) {
+                this.lastAction = truncate(firstLine, MAX_TASK_LENGTH);
+            }
+        }
+    }
     transitionTo(newPhase) {
-        if (this.phaseOrder(newPhase) <= this.phaseOrder(this.phase))
+        if (PHASE_ORDER[newPhase] <= PHASE_ORDER[this.phase])
             return;
         log.info(TAG, `Phase: ${this.phase} → ${newPhase}`);
         this.phase = newPhase;
         this.progress = Math.max(this.progress, PHASES[newPhase].min);
-        this.scheduleUpdate(PHASES[newPhase].task);
+        // Reset stale action from prior phase; new phase starts with its own label
+        this.lastAction = "";
+        this.scheduleUpdate(PHASES[newPhase].label);
     }
     incrementProgress() {
         const config = PHASES[this.phase];
         const range = config.max - config.min;
-        // Each tool call moves ~2% within the phase, so roughly 7-15 calls fill a phase
         const step = Math.max(1, Math.round(range / 12));
         const newProgress = Math.min(this.progress + step, config.max);
         if (newProgress > this.progress) {
@@ -120,29 +215,106 @@ export class ProgressTracker {
         }
     }
     currentTaskLabel() {
-        const config = PHASES[this.phase];
-        return config.task;
+        if (this.lastAction)
+            return this.lastAction;
+        // Include file count context when available
+        const edited = this.filesEdited.size;
+        if (edited > 0) {
+            return `${PHASES[this.phase].label} (${edited} file${edited > 1 ? "s" : ""} modified)`;
+        }
+        return PHASES[this.phase].label;
+    }
+    /**
+     * Build a human-readable description of what a tool call is doing.
+     */
+    describeToolAction(name, input) {
+        // File-based tools: Read, Edit, MultiEdit, Write, NotebookEdit
+        const fileTool = FILE_TOOL_VERBS[name];
+        if (fileTool) {
+            const [verb, key] = fileTool;
+            const fp = this.extractString(input, key);
+            return fp ? `${verb} ${this.shortPath(fp)}` : verb;
+        }
+        switch (name) {
+            case "Glob": {
+                const pattern = this.extractString(input, "pattern");
+                return pattern ? `Searching for ${pattern}` : "Searching files";
+            }
+            case "Grep": {
+                const pattern = this.extractString(input, "pattern");
+                return pattern
+                    ? `Searching for "${truncate(pattern, 40)}"`
+                    : "Searching code";
+            }
+            case "Bash": {
+                const cmd = this.extractString(input, "command");
+                return cmd
+                    ? `Running: ${truncate(cmd.split("\n")[0], 80)}`
+                    : "Running command";
+            }
+            case "Agent": {
+                const desc = this.extractString(input, "description");
+                return desc
+                    ? `Sub-agent: ${truncate(desc, 60)}`
+                    : "Delegating to sub-agent";
+            }
+            default: {
+                if (name.startsWith("mcp__harmony__harmony_")) {
+                    const toolName = name
+                        .replace("mcp__harmony__harmony_", "")
+                        .replace(/_/g, " ");
+                    return `Harmony: ${toolName}`;
+                }
+                if (name.startsWith("mcp__")) {
+                    return `Tool: ${name.split("__").pop()?.replace(/_/g, " ") ?? name}`;
+                }
+                return null;
+            }
+        }
+    }
+    /**
+     * Strip absolute paths to show only meaningful segments from src/ or packages/.
+     */
+    shortPath(filePath) {
+        const parts = filePath.split("/");
+        const srcIdx = parts.lastIndexOf("src");
+        const pkgIdx = parts.lastIndexOf("packages");
+        const anchor = Math.max(srcIdx, pkgIdx);
+        if (anchor >= 0) {
+            return parts.slice(anchor).join("/");
+        }
+        return parts.slice(-3).join("/");
     }
     scheduleUpdate(currentTask) {
         if (this.stopped)
             return;
         const now = Date.now();
         const elapsed = now - this.lastUpdateAt;
+        // Always track latest task so throttled sends use the freshest label
+        this.pendingTask = currentTask;
         if (elapsed >= THROTTLE_MS) {
-            // Can send immediately
-            this.sendUpdate(currentTask);
+            this.sendUpdate(this.pendingTask);
         }
         else if (!this.pendingUpdate) {
-            // Schedule for after throttle window
             const delay = THROTTLE_MS - elapsed;
             this.pendingUpdate = setTimeout(() => {
                 this.pendingUpdate = null;
                 if (!this.stopped) {
-                    this.sendUpdate(currentTask);
+                    // Send the latest task, not the one captured at schedule time
+                    this.sendUpdate(this.pendingTask);
                 }
             }, delay);
         }
-        // If there's already a pending update, it will fire soon — skip
+        // If there's already a pending update, pendingTask is now updated — it will use the fresh value
+    }
+    pushRecentAction(action) {
+        this.recentActions.push({
+            action,
+            ts: new Date().toISOString(),
+        });
+        if (this.recentActions.length > MAX_RECENT_ACTIONS) {
+            this.recentActions.shift();
+        }
     }
     sendUpdate(currentTask) {
         this.lastUpdateAt = Date.now();
@@ -152,8 +324,12 @@ export class ProgressTracker {
             agentIdentifier: agentIdentifier(this.workerId),
             agentName: AGENT_NAME,
             status: "working",
-            currentTask,
+            currentTask: truncate(currentTask, MAX_TASK_LENGTH),
             progressPercent: this.progress,
+            phase: this.phase,
+            filesChanged: this.filesEdited.size,
+            costCents: Math.round((this.lastCost?.totalCostUsd ?? 0) * 100),
+            recentActions: this.recentActions,
         })
             .catch((err) => {
             log.warn(TAG, `Failed to send progress update: ${err}`);
@@ -165,24 +341,20 @@ export class ProgressTracker {
         }
         this.heartbeatTimer = setTimeout(() => {
             if (!this.stopped) {
-                this.sendUpdate("Still working...");
+                const task = this.lastAction
+                    ? `Still working — ${this.lastAction}`
+                    : "Still working...";
+                this.sendUpdate(truncate(task, MAX_TASK_LENGTH));
                 this.startHeartbeat();
             }
         }, HEARTBEAT_MS);
     }
-    phaseOrder(phase) {
-        const order = [
-            "exploring",
-            "implementing",
-            "testing",
-            "committing",
-            "finishing",
-        ];
-        return order.indexOf(phase);
-    }
-    extractBashCommand(input) {
-        if (typeof input === "object" && input !== null && "command" in input) {
-            return String(input.command);
+    /**
+     * Safely extract a string property from an unknown tool input.
+     */
+    extractString(input, key) {
+        if (typeof input === "object" && input !== null && key in input) {
+            return String(input[key]);
         }
         return null;
     }

package/dist/reconcile.js

@@ -1,5 +1,6 @@
-import { hasApprovedLabel } from "./board-helpers.js";
+import { buildLabelMap, hasLabel, resolveCardLabels } from "./board-helpers.js";
 import { log } from "./log.js";
+import { NEED_REVIEW_LABEL } from "./types.js";
 const TAG = "reconcile";
 /**
  * Reconciliation heartbeat: polls the board every `intervalMs` to catch
@@ -42,8 +43,9 @@ export class Reconciler {
         try {
             const board = await this.client.getBoard(this.projectId);
             const cards = (board.cards ?? []);
-            const columns = board.columns;
-            const _labels = (board.labels ?? []);
+            const columns = (board.columns ?? []);
+            // Build label lookup (id → Label) to resolve card.labelIds
+            const labelMap = buildLabelMap((board.labels ?? []));
             // Build a lookup of columns by ID
             const columnMap = new Map();
             for (const col of columns) {
@@ -74,7 +76,7 @@ export class Reconciler {
                     const column = columnMap.get(card.column_id);
                     if (!column)
                         continue;
-                    const cardLabels = card.labels ?? [];
+                    const cardLabels = resolveCardLabels(card, labelMap);
                     const subtasks = card.subtasks ?? [];
                     // Determine mode based on which column set the card is in
                     const mode = reviewColumnIds.has(card.column_id)
@@ -83,10 +85,15 @@ export class Reconciler {
                     // Skip already-approved cards in review mode
                     if (mode === "review" &&
                         this.approvedLabel &&
-                        hasApprovedLabel(cardLabels, this.approvedLabel)) {
+                        hasLabel(cardLabels, this.approvedLabel)) {
                         log.debug(TAG, `Skipping #${card.short_id} — already has "${this.approvedLabel}" label`);
                         continue;
                     }
+                    // Skip cards with "Need Review" label (awaiting human review)
+                    if (mode === "review" && hasLabel(cardLabels, NEED_REVIEW_LABEL)) {
+                        log.debug(TAG, `Skipping #${card.short_id} — has "${NEED_REVIEW_LABEL}" label (needs human)`);
+                        continue;
+                    }
                     log.info(TAG, `Missed assignment: #${card.short_id} "${card.title}" (${mode}) — enqueueing`);
                     this.pool.enqueue(card, column, cardLabels, subtasks, mode);
                 }

package/dist/review-completion.d.ts

@@ -28,4 +28,4 @@ export declare function parseReviewOutput(stdout: string): ReviewResult;
  * Handles approved/rejected verdicts, creates subtasks for findings,
  * and moves the card to the appropriate column.
  */
-export declare function runReviewCompletion(client: HarmonyApiClient, card: Card, result: ReviewResult, config: AgentConfig, worktreePath: string, branchName: string): Promise<void>;
+export declare function runReviewCompletion(client: HarmonyApiClient, card: Card, result: ReviewResult, config: AgentConfig, worktreePath: string, branchName: string | null): Promise<void>;

package/dist/review-completion.js

@@ -110,13 +110,15 @@ export async function runReviewCompletion(client, card, result, config, worktree
     const currentCycle = getReviewCycle(freshDesc) + 1;
     const maxCycles = config.review.maxReviewCycles;
     if (result.verdict === "approved") {
-        // Ensure branch is pushed (may need force-push after rework)
-        pushBranch(branchName, worktreePath);
-        // Create PR if configured
+        // Ensure branch is pushed (skip in local mode — no branch to push)
         let prUrl = null;
-        if (config.review.createPR) {
-            const provider = detectGitProvider(worktreePath);
-            prUrl = createPullRequest(card, branchName, worktreePath, config, provider);
+        if (branchName) {
+            pushBranch(branchName, worktreePath);
+            // Create PR if configured
+            if (config.review.createPR) {
+                const provider = detectGitProvider(worktreePath);
+                prUrl = createPullRequest(card, branchName, worktreePath, config, provider);
+            }
         }
         // Add "Ready to Merge" label
         await addLabelByName(client, card, config.review.approvedLabel, config.review.approvedLabelColor);
@@ -180,7 +182,9 @@ export async function runReviewCompletion(client, card, result, config, worktree
                 log.error(TAG, `Failed to update description: ${err instanceof Error ? err.message : err}`);
             }
             await client.endAgentSession(card.id, { status: "completed" });
-            cleanupWorktree(worktreePath, branchName);
+            if (branchName) {
+                cleanupWorktree(worktreePath, branchName);
+            }
             return;
         }
         // Post findings
@@ -242,6 +246,8 @@ export async function runReviewCompletion(client, card, result, config, worktree
         await client.endAgentSession(card.id, { status: "paused" });
         log.info(TAG, `#${card.short_id} rejected (cycle ${currentCycle}/${maxCycles}) — moved to "${config.review.failColumn}"`);
     }
-    // Cleanup worktree
-    cleanupWorktree(worktreePath, branchName);
+    // Cleanup worktree (skip in local mode — no worktree to clean)
+    if (branchName) {
+        cleanupWorktree(worktreePath, branchName);
+    }
 }

package/dist/review-prompt.d.ts

@@ -9,4 +9,4 @@ export declare function buildReviewSystemPrompt(): string;
  * Build the card-specific user prompt for the review agent.
  * Contains the diff, requirements, and structured review steps.
  */
-export declare function buildReviewUserPrompt(enriched: EnrichedCard, branchName: string, worktreePath: string, previewUrl: string, diff: string): string;
+export declare function buildReviewUserPrompt(enriched: EnrichedCard, branchName: string | null, worktreePath: string, previewUrl: string, diff: string, baseBranch: string): string;

package/dist/review-prompt.js

@@ -16,7 +16,7 @@ ${QA_VISUAL_CHECKLIST}`;
  * Build the card-specific user prompt for the review agent.
  * Contains the diff, requirements, and structured review steps.
  */
-export function buildReviewUserPrompt(enriched, branchName, worktreePath, previewUrl, diff) {
+export function buildReviewUserPrompt(enriched, branchName, worktreePath, previewUrl, diff, baseBranch) {
     const { card, labels, subtasks } = enriched;
     const labelStr = labels.length > 0 ? labels.map((l) => l.name).join(", ") : "none";
     const subtaskStr = subtasks.length > 0
@@ -28,9 +28,12 @@ export function buildReviewUserPrompt(enriched, branchName, worktreePath, previe
     const truncatedDiff = diff.length > 80_000
         ? `${diff.slice(0, 80_000)}\n\n... (diff truncated at 80K characters)`
         : diff;
+    const branchLine = branchName
+        ? `**Branch**: ${branchName}`
+        : `**Mode**: Local review (no branch — reviewing working tree changes)`;
     return `## Card: #${card.short_id} - ${card.title}
 **Labels**: ${labelStr}
-**Branch**: ${branchName}
+${branchLine}
 
 ## Original Requirements
 ${description}
@@ -38,7 +41,7 @@ ${description}
 ## Subtasks (Acceptance Criteria)
 ${subtaskStr}
 
-## Diff (origin/main..HEAD)
+## Diff ${branchName ? `(origin/${baseBranch}..HEAD)` : "(local changes)"}
 \`\`\`diff
 ${truncatedDiff}
 \`\`\`
@@ -96,5 +99,5 @@ After completing all steps, output EXACTLY one JSON block (and nothing else afte
 - **approved**: No critical findings, at most 1 major finding with minor findings OK.
 
 **Do NOT modify any code.** This is a read-only review.
-You are reviewing code in a git worktree at \`${worktreePath}\` on branch \`${branchName}\`.`;
+${branchName ? `You are reviewing code in a git worktree at \`${worktreePath}\` on branch \`${branchName}\`.` : `You are reviewing local changes in the repository at \`${worktreePath}\`.`}`;
 }

package/dist/review-worker.d.ts

@@ -14,20 +14,31 @@ export declare class ReviewWorker {
     private process;
     private devServerProcess;
     private timeoutTimer;
+    private progressTracker;
     private aborted;
     constructor(id: number, config: AgentConfig, client: HarmonyApiClient, _userEmail: string, onDone: (worker: ReviewWorker) => void);
     get tag(): string;
     get isIdle(): boolean;
+    private get reviewPort();
     get isActive(): boolean;
     /**
      * Start reviewing a card. Runs the full lifecycle:
      * PREPARING → REVIEWING → COMPLETING → IDLE
      */
     run(card: Card, column: Column, labels: Label[], subtasks: Subtask[]): Promise<void>;
+    /**
+     * Pause the current review by suspending the Claude process (SIGSTOP).
+     */
+    pause(): Promise<void>;
+    /**
+     * Resume the Claude process after a pause (SIGCONT).
+     */
+    resume(): Promise<void>;
     /**
      * Cancel the current review. Sends escalating signals to both processes.
      */
     cancel(): Promise<void>;
+    private checkDevServer;
     private spawnClaude;
     private waitForExit;
     private killDevServer;