@gethmy/agent 1.0.1 → 1.0.3

package/dist/review-worker.js

@@ -1,10 +1,12 @@
 import { execFileSync, spawn } from "node:child_process";
 import { addLabelByName, moveCardToColumn } from "./board-helpers.js";
 import { log } from "./log.js";
+import { ProgressTracker } from "./progress-tracker.js";
 import { parseReviewOutput, runReviewCompletion } from "./review-completion.js";
 import { buildReviewSystemPrompt, buildReviewUserPrompt, } from "./review-prompt.js";
 import { checkoutExistingBranch, extractBranchFromDescription, } from "./review-worktree.js";
-import { AGENT_NAME, agentIdentifier, } from "./types.js";
+import { StreamParser } from "./stream-parser.js";
+import { AGENT_NAME, agentIdentifier, NEED_REVIEW_LABEL, NEED_REVIEW_LABEL_COLOR, } from "./types.js";
 import { waitForDevServer } from "./verification.js";
 import { cleanupWorktree } from "./worktree.js";
 const TAG = "review-worker";
@@ -23,6 +25,7 @@ export class ReviewWorker {
     process = null;
     devServerProcess = null;
     timeoutTimer = null;
+    progressTracker = null;
     aborted = false;
     constructor(id, config, client, _userEmail, onDone) {
         this.config = config;
@@ -36,6 +39,9 @@ export class ReviewWorker {
     get isIdle() {
         return this.state === "idle";
     }
+    get reviewPort() {
+        return this.config.review.devServerPort + (this.id - this.config.poolSize);
+    }
     get isActive() {
         return (this.state === "preparing" ||
             this.state === "running" ||
@@ -56,45 +62,93 @@ export class ReviewWorker {
             log.info(this.tag, `Preparing review for #${card.short_id} "${card.title}"`);
             // Extract branch name from card description
             this.branchName = extractBranchFromDescription(card.description);
-            if (!this.branchName) {
-                throw new Error(`No branch name found in card #${card.short_id} description. ` +
-                    "Expected: Branch: `agent/...`");
+            const localMode = !this.branchName;
+            if (localMode) {
+                // LOCAL FALLBACK: no branch → review local working tree
+                log.info(this.tag, `No branch found for #${card.short_id}, attempting local review`);
+                // Use repo root as working directory
+                this.worktreePath = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+                    cwd: this.config.worktree.basePath,
+                    encoding: "utf-8",
+                    timeout: 5_000,
+                }).trim();
+                // Check if dev server is already running on the configured port
+                const serverRunning = await this.checkDevServer(this.reviewPort);
+                if (!serverRunning) {
+                    log.info(this.tag, `No dev server on port ${this.reviewPort} — adding "${NEED_REVIEW_LABEL}" label and moving to "${this.config.review.failColumn}"`);
+                    await Promise.all([
+                        addLabelByName(this.client, card, NEED_REVIEW_LABEL, NEED_REVIEW_LABEL_COLOR),
+                        moveCardToColumn(this.client, card, this.config.review.failColumn),
+                    ]);
+                    return;
+                }
+            }
+            if (this.branchName) {
+                log.info(this.tag, `Review branch: ${this.branchName}`);
             }
-            log.info(this.tag, `Review branch: ${this.branchName}`);
             // Start agent session and make it visible on the board
             await this.client.startAgentSession(card.id, {
                 agentIdentifier: agentIdentifier(this.id),
                 agentName: `${AGENT_NAME} (Review)`,
                 status: "working",
-                currentTask: "Setting up review worktree",
+                currentTask: localMode
+                    ? "Reviewing local changes"
+                    : "Setting up review worktree",
                 progressPercent: 5,
             });
             // Fire label addition concurrently with sync worktree checkout
             const labelPromise = addLabelByName(this.client, card, "agent", "#8b5cf6");
-            // Checkout existing branch into worktree (sync)
-            this.worktreePath = checkoutExistingBranch(this.config.worktree.basePath, this.branchName);
+            if (!localMode) {
+                // Checkout existing branch into worktree (sync)
+                this.worktreePath = checkoutExistingBranch(this.config.worktree.basePath, this.branchName);
+            }
             await labelPromise;
             if (this.aborted)
                 return;
             // --- REVIEWING ---
             this.state = "running";
-            // Start dev server
-            // Use devServerPort directly — review worker IDs are offset by poolSize
-            // so we subtract to get a 0-based index for port allocation
-            const port = this.config.review.devServerPort + (this.id - this.config.poolSize);
-            log.info(this.tag, `Starting dev server on port ${port}...`);
-            this.devServerProcess = spawn("bun", ["run", "dev", "--", "--port", String(port)], {
-                cwd: this.worktreePath,
-                stdio: ["ignore", "pipe", "pipe"],
-            });
-            await waitForDevServer(this.devServerProcess, 30_000);
-            log.info(this.tag, `Dev server ready on port ${port}`);
+            if (!this.worktreePath) {
+                throw new Error("worktreePath not set before review phase");
+            }
+            // Start dev server (only in branch mode — local mode uses existing server)
+            const port = this.reviewPort;
+            const cwd = this.worktreePath;
+            if (!localMode) {
+                log.info(this.tag, `Starting dev server on port ${port}...`);
+                this.devServerProcess = spawn("bun", ["run", "dev", "--", "--port", String(port)], { cwd, stdio: ["ignore", "pipe", "pipe"] });
+                await waitForDevServer(this.devServerProcess, 30_000);
+                log.info(this.tag, `Dev server ready on port ${port}`);
+            }
             if (this.aborted)
                 return;
             // Get diff
             let diff = "";
             try {
-                diff = execFileSync("git", ["diff", `origin/${this.config.worktree.baseBranch}..HEAD`], { cwd: this.worktreePath, encoding: "utf-8", timeout: 30_000 });
+                if (localMode) {
+                    // Local mode: show uncommitted changes or last commit's diff
+                    const uncommitted = execFileSync("git", ["diff"], {
+                        cwd,
+                        encoding: "utf-8",
+                        timeout: 30_000,
+                    });
+                    const staged = execFileSync("git", ["diff", "--cached"], {
+                        cwd,
+                        encoding: "utf-8",
+                        timeout: 30_000,
+                    });
+                    diff = [staged, uncommitted].filter(Boolean).join("\n");
+                    if (!diff) {
+                        // No uncommitted changes — get last commit's diff
+                        diff = execFileSync("git", ["diff", "HEAD~1..HEAD"], {
+                            cwd,
+                            encoding: "utf-8",
+                            timeout: 30_000,
+                        });
+                    }
+                }
+                else {
+                    diff = execFileSync("git", ["diff", `origin/${this.config.worktree.baseBranch}..HEAD`], { cwd, encoding: "utf-8", timeout: 30_000 });
+                }
             }
             catch {
                 diff = "(unable to retrieve diff)";
@@ -108,7 +162,7 @@ export class ReviewWorker {
                 mode: "review",
             };
             const systemPrompt = buildReviewSystemPrompt();
-            const userPrompt = buildReviewUserPrompt(enriched, this.branchName, this.worktreePath, previewUrl, diff);
+            const userPrompt = buildReviewUserPrompt(enriched, this.branchName, cwd, previewUrl, diff, this.config.worktree.baseBranch);
             await this.client.updateAgentProgress(card.id, {
                 agentIdentifier: agentIdentifier(this.id),
                 agentName: `${AGENT_NAME} (Review)`,
@@ -121,15 +175,21 @@ export class ReviewWorker {
                 log.warn(this.tag, `Review timeout reached (${this.config.review.maxTimeout}ms), cancelling`);
                 this.cancel();
             }, this.config.review.maxTimeout);
-            // Spawn Claude CLI for review
-            const stdout = await this.spawnClaude(userPrompt, systemPrompt);
+            // Set up progress tracking
+            this.progressTracker = new ProgressTracker(this.client, card.id, this.id, subtasks);
+            // Spawn Claude CLI for review with streaming
+            const stdout = await this.spawnClaude(userPrompt, systemPrompt, this.progressTracker);
+            this.progressTracker.stop();
+            this.progressTracker = null;
             if (this.aborted)
                 return;
             // --- COMPLETING ---
             this.state = "completing";
             log.info(this.tag, `Claude review finished for #${card.short_id}`);
-            // Kill dev server
-            this.killDevServer();
+            // Kill dev server (only if we started one)
+            if (!localMode) {
+                this.killDevServer();
+            }
             // Parse findings
             const result = parseReviewOutput(stdout);
             log.info(this.tag, `Review verdict: ${result.verdict} (${result.findings.length} finding(s))`);
@@ -141,7 +201,7 @@ export class ReviewWorker {
                 progressPercent: 80,
             });
             // Run review completion pipeline
-            await runReviewCompletion(this.client, card, result, this.config, this.worktreePath, this.branchName);
+            await runReviewCompletion(this.client, card, result, this.config, cwd, this.branchName);
         }
         catch (err) {
             this.state = "error";
@@ -169,6 +229,58 @@ export class ReviewWorker {
             this.onDone(this);
         }
     }
+    /**
+     * Pause the current review by suspending the Claude process (SIGSTOP).
+     */
+    async pause() {
+        if (!this.isActive || !this.process || this.process.killed)
+            return;
+        log.info(this.tag, `Pausing review on ${this.cardId}`);
+        this.process.kill("SIGSTOP");
+        if (this.timeoutTimer) {
+            clearTimeout(this.timeoutTimer);
+            this.timeoutTimer = null;
+        }
+        // Update agent session so the UI reflects the paused state
+        if (this.cardId) {
+            try {
+                await this.client.updateAgentProgress(this.cardId, {
+                    agentIdentifier: agentIdentifier(this.id),
+                    agentName: AGENT_NAME,
+                    status: "paused",
+                });
+            }
+            catch {
+                log.warn(this.tag, "Failed to update agent session to paused");
+            }
+        }
+    }
+    /**
+     * Resume the Claude process after a pause (SIGCONT).
+     */
+    async resume() {
+        if (!this.isActive || !this.process || this.process.killed)
+            return;
+        log.info(this.tag, `Resuming review on ${this.cardId}`);
+        this.process.kill("SIGCONT");
+        this.timeoutTimer = setTimeout(() => {
+            log.warn(this.tag, `Timeout reached (${this.config.review.maxTimeout}ms), cancelling`);
+            this.cancel();
+        }, this.config.review.maxTimeout);
+        // Update agent session so the UI reflects the resumed state
+        if (this.cardId) {
+            try {
+                await this.client.updateAgentProgress(this.cardId, {
+                    agentIdentifier: agentIdentifier(this.id),
+                    agentName: AGENT_NAME,
+                    status: "working",
+                });
+            }
+            catch {
+                log.warn(this.tag, "Failed to update agent session to working");
+            }
+        }
+    }
     /**
      * Cancel the current review. Sends escalating signals to both processes.
      */
@@ -178,10 +290,17 @@ export class ReviewWorker {
         this.aborted = true;
         this.state = "cancelling";
         log.info(this.tag, `Cancelling review on ${this.cardId}`);
+        // Stop progress tracking
+        if (this.progressTracker) {
+            this.progressTracker.stop();
+            this.progressTracker = null;
+        }
         // Kill dev server first
         this.killDevServer();
         // Then kill Claude process with escalating signals
         if (this.process && !this.process.killed) {
+            // Resume first in case the process is suspended
+            this.process.kill("SIGCONT");
             this.process.kill("SIGINT");
             log.debug(this.tag, "Sent SIGINT to Claude");
             const sigintDead = await this.waitForExit(CANCEL_SIGINT_TIMEOUT);
@@ -205,10 +324,23 @@ export class ReviewWorker {
             }
         }
     }
-    spawnClaude(prompt, systemPrompt) {
+    async checkDevServer(port) {
+        try {
+            const resp = await fetch(`http://localhost:${port}`, {
+                signal: AbortSignal.timeout(3_000),
+            });
+            return resp.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+    spawnClaude(prompt, systemPrompt, tracker) {
         return new Promise((resolve, reject) => {
             const args = [
-                "--print",
+                "--output-format",
+                "stream-json",
+                "--verbose",
                 "--model",
                 this.config.claude.model,
                 "--max-turns",
@@ -220,22 +352,23 @@ export class ReviewWorker {
                 "--",
                 prompt,
             ];
-            log.info(this.tag, `Spawning review: claude ${args.slice(0, 3).join(" ")} ...`);
+            log.info(this.tag, `Spawning review: claude ${args.slice(0, 5).join(" ")} ...`);
             this.process = spawn("claude", args, {
                 cwd: this.worktreePath,
                 stdio: ["ignore", "pipe", "pipe"],
             });
-            let stdout = "";
-            let stderr = "";
-            this.process.stdout?.on("data", (data) => {
-                const text = data.toString();
-                stdout += text;
-                for (const line of text.split("\n")) {
-                    if (line.trim()) {
-                        log.debug(this.tag, `claude> ${line.slice(0, 200)}`);
-                    }
-                }
+            // Stream parser for progress tracking + text reconstruction for verdict
+            const parser = new StreamParser();
+            tracker.attach(parser);
+            const textChunks = [];
+            parser.on("text", (content) => {
+                textChunks.push(content);
             });
+            // Attach parser to stdout (single consumer)
+            if (this.process.stdout) {
+                parser.attach(this.process.stdout);
+            }
+            let stderr = "";
             this.process.stderr?.on("data", (data) => {
                 stderr += data.toString();
             });
@@ -244,6 +377,8 @@ export class ReviewWorker {
             });
             this.process.on("close", (code) => {
                 this.process = null;
+                // Reconstruct text from stream parser text events
+                const stdout = textChunks.join("");
                 if (this.aborted) {
                     resolve(stdout);
                 }
@@ -284,10 +419,10 @@ export class ReviewWorker {
             this.timeoutTimer = null;
         }
         this.killDevServer();
-        // Clean up worktree on error
-        if (this.worktreePath && this.state === "error") {
+        // Clean up worktree on error (only if we created one — skip in local mode)
+        if (this.worktreePath && this.state === "error" && this.branchName) {
             try {
-                cleanupWorktree(this.worktreePath, this.branchName ?? undefined);
+                cleanupWorktree(this.worktreePath, this.branchName);
             }
             catch {
                 log.warn(this.tag, "Failed to cleanup review worktree");

package/dist/stream-parser.d.ts

@@ -1,21 +1,30 @@
 import { EventEmitter } from "node:events";
 import type { Readable } from "node:stream";
+export interface CostUpdate {
+    totalCostUsd: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    durationMs: number;
+    durationApiMs: number;
+    numTurns: number;
+}
 export interface StreamParserEvents {
     tool_start: [name: string, input: unknown];
-    tool_end: [name: string, toolUseId: string];
+    tool_end: [name: string, toolUseId: string, content: string | undefined];
     text: [content: string];
     result: [stopReason: string];
-    error: [msg: string];
+    cost_update: [cost: CostUpdate];
+    parse_error: [msg: string];
 }
 export declare class StreamParser extends EventEmitter<StreamParserEvents> {
     private buffer;
-    private finalText;
-    get outputText(): string;
+    private attached;
     /**
-     * Pipe a readable stream (Claude CLI stdout) through the parser.
-     * Returns when the stream ends.
+     * Attach a readable stream (Claude CLI stdout) to the parser.
+     * Parses NDJSON lines and emits typed events.
+     * Each instance must only be attached once.
      */
-    pipe(stream: Readable): void;
+    attach(stream: Readable): void;
     private flush;
     private parseLine;
     private handleMessage;

package/dist/stream-parser.js

@@ -3,15 +3,17 @@ import { log } from "./log.js";
 const TAG = "stream-parser";
 export class StreamParser extends EventEmitter {
     buffer = "";
-    finalText = "";
-    get outputText() {
-        return this.finalText;
-    }
+    attached = false;
     /**
-     * Pipe a readable stream (Claude CLI stdout) through the parser.
-     * Returns when the stream ends.
+     * Attach a readable stream (Claude CLI stdout) to the parser.
+     * Parses NDJSON lines and emits typed events.
+     * Each instance must only be attached once.
      */
-    pipe(stream) {
+    attach(stream) {
+        if (this.attached) {
+            throw new Error("StreamParser already attached to a stream");
+        }
+        this.attached = true;
         stream.on("data", (chunk) => {
             this.buffer += chunk.toString();
             this.flush();
@@ -50,7 +52,7 @@ export class StreamParser extends EventEmitter {
         catch (err) {
             const errMsg = err instanceof Error ? err.message : String(err);
             log.warn(TAG, `Error handling stream event: ${errMsg}`);
-            this.emit("error", errMsg);
+            this.emit("parse_error", errMsg);
         }
     }
     handleMessage(msg) {
@@ -60,14 +62,13 @@ export class StreamParser extends EventEmitter {
                     this.emit("tool_start", msg.tool_name, msg.input);
                 }
                 else if (msg.subtype === "text" && msg.content) {
-                    this.finalText += msg.content;
                     this.emit("text", msg.content);
                 }
                 break;
             }
             case "tool_result": {
                 if (msg.tool_use_id && msg.tool_name) {
-                    this.emit("tool_end", msg.tool_name, msg.tool_use_id);
+                    this.emit("tool_end", msg.tool_name, msg.tool_use_id, msg.content);
                 }
                 break;
             }
@@ -75,7 +76,20 @@ export class StreamParser extends EventEmitter {
                 this.emit("result", msg.stop_reason ?? "unknown");
                 break;
             }
-            // Ignore system, ping, cost_update, etc.
+            case "cost_update": {
+                if (msg.total_cost_usd != null) {
+                    this.emit("cost_update", {
+                        totalCostUsd: msg.total_cost_usd,
+                        totalInputTokens: msg.total_input_tokens ?? 0,
+                        totalOutputTokens: msg.total_output_tokens ?? 0,
+                        durationMs: msg.duration_ms ?? 0,
+                        durationApiMs: msg.duration_api_ms ?? 0,
+                        numTurns: msg.num_turns ?? 0,
+                    });
+                }
+                break;
+            }
+            // Ignore system, ping, etc.
         }
     }
 }

package/dist/types.d.ts

@@ -49,6 +49,8 @@ export interface AgentConfig {
     };
 }
 export declare const DEFAULT_AGENT_CONFIG: AgentConfig;
+export declare const NEED_REVIEW_LABEL = "Need Review";
+export declare const NEED_REVIEW_LABEL_COLOR = "#f59e0b";
 export declare const AGENT_NAME = "Harmony Agent";
 export declare function agentIdentifier(workerId: number): string;
 export type ProgressPhase = "exploring" | "implementing" | "testing" | "committing" | "finishing";

package/dist/types.js

@@ -46,6 +46,9 @@ export const DEFAULT_AGENT_CONFIG = {
         mergedLabelColor: "#6366f1",
     },
 };
+// ============ LABELS ============
+export const NEED_REVIEW_LABEL = "Need Review";
+export const NEED_REVIEW_LABEL_COLOR = "#f59e0b";
 // ============ AGENT IDENTITY ============
 export const AGENT_NAME = "Harmony Agent";
 export function agentIdentifier(workerId) {

package/dist/watcher.d.ts

@@ -3,7 +3,12 @@ export interface CardBroadcastEvent {
     event: "card_update" | "card_created";
     payload: Record<string, unknown>;
 }
+export interface AgentCommandEvent {
+    cardId: string;
+    command: "pause" | "resume" | "stop";
+}
 export type CardBroadcastHandler = (event: CardBroadcastEvent) => void;
+export type AgentCommandHandler = (event: AgentCommandEvent) => void;
 /**
  * Subscribes to Supabase broadcast events on the board channel.
  * The harmony-api broadcasts card_update and card_created events
@@ -13,9 +18,10 @@ export declare class Watcher {
     private credentials;
     private projectId;
     private onCardBroadcast;
+    private onAgentCommand?;
     private channel;
     private supabase;
-    constructor(credentials: RealtimeCredentials, projectId: string, onCardBroadcast: CardBroadcastHandler);
+    constructor(credentials: RealtimeCredentials, projectId: string, onCardBroadcast: CardBroadcastHandler, onAgentCommand?: AgentCommandHandler | undefined);
     start(): Promise<void>;
     stop(): Promise<void>;
 }

package/dist/watcher.js

@@ -10,17 +10,19 @@ export class Watcher {
     credentials;
     projectId;
     onCardBroadcast;
+    onAgentCommand;
     channel = null;
     supabase = null;
-    constructor(credentials, projectId, onCardBroadcast) {
+    constructor(credentials, projectId, onCardBroadcast, onAgentCommand) {
         this.credentials = credentials;
         this.projectId = projectId;
         this.onCardBroadcast = onCardBroadcast;
+        this.onAgentCommand = onAgentCommand;
     }
     async start() {
         log.info(TAG, "Connecting to Supabase realtime (broadcast)...");
         this.supabase = createClient(this.credentials.supabaseUrl, this.credentials.supabaseAnonKey);
-        this.channel = this.supabase
+        const channel = this.supabase
             .channel(`board-${this.projectId}`)
             .on("broadcast", { event: "card_update" }, (msg) => {
             log.debug(TAG, `Broadcast: card_update ${JSON.stringify(msg.payload)}`);
@@ -35,6 +37,15 @@ export class Watcher {
                 event: "card_created",
                 payload: msg.payload ?? {},
             });
+        })
+            .on("broadcast", { event: "agent_command" }, (msg) => {
+            const payload = msg.payload ?? {};
+            const cardId = payload.card_id;
+            const command = payload.command;
+            if (cardId && command) {
+                log.info(TAG, `Broadcast: agent_command ${command} for ${cardId}`);
+                this.onAgentCommand?.({ cardId, command });
+            }
         })
             .subscribe((status) => {
             if (status === "SUBSCRIBED") {
@@ -47,6 +58,7 @@ export class Watcher {
                 log.warn(TAG, "Broadcast subscription timed out — retrying...");
             }
         });
+        this.channel = channel;
     }
     async stop() {
         if (this.channel) {

package/dist/worker.d.ts

@@ -14,6 +14,7 @@ export declare class Worker {
     private process;
     private timeoutTimer;
     private progressTracker;
+    private lastSessionStats;
     private aborted;
     constructor(id: number, config: AgentConfig, client: HarmonyApiClient, _userEmail: string, onDone: (worker: Worker) => void);
     get tag(): string;
@@ -24,6 +25,14 @@ export declare class Worker {
      * PREPARING → RUNNING → COMPLETING → IDLE
      */
     run(card: Card, column: Column, labels: Label[], subtasks: Subtask[]): Promise<void>;
+    /**
+     * Pause the current work by suspending the Claude process (SIGSTOP).
+     */
+    pause(): Promise<void>;
+    /**
+     * Resume the Claude process after a pause (SIGCONT).
+     */
+    resume(): Promise<void>;
     /**
      * Cancel the current work. Sends escalating signals to the Claude process.
      */