@gethmy/agent 1.0.0 → 1.0.2

package/dist/review-worker.js

@@ -0,0 +1,437 @@
+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 { 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";
+const CANCEL_SIGINT_TIMEOUT = 30_000;
+const CANCEL_SIGTERM_TIMEOUT = 10_000;
+export class ReviewWorker {
+    config;
+    client;
+    onDone;
+    id;
+    state = "idle";
+    cardId = null;
+    branchName = null;
+    worktreePath = null;
+    startedAt = null;
+    process = null;
+    devServerProcess = null;
+    timeoutTimer = null;
+    progressTracker = null;
+    aborted = false;
+    constructor(id, config, client, _userEmail, onDone) {
+        this.config = config;
+        this.client = client;
+        this.onDone = onDone;
+        this.id = id;
+    }
+    get tag() {
+        return `${TAG}:${this.id}`;
+    }
+    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" ||
+            this.state === "verifying" ||
+            this.state === "completing");
+    }
+    /**
+     * Start reviewing a card. Runs the full lifecycle:
+     * PREPARING → REVIEWING → COMPLETING → IDLE
+     */
+    async run(card, column, labels, subtasks) {
+        this.aborted = false;
+        this.cardId = card.id;
+        this.startedAt = Date.now();
+        try {
+            // --- PREPARING ---
+            this.state = "preparing";
+            log.info(this.tag, `Preparing review for #${card.short_id} "${card.title}"`);
+            // Extract branch name from card description
+            this.branchName = extractBranchFromDescription(card.description);
+            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}`);
+            }
+            // 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: 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");
+            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";
+            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 {
+                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)";
+            }
+            const previewUrl = `http://localhost:${port}`;
+            const enriched = {
+                card,
+                column,
+                labels,
+                subtasks,
+                mode: "review",
+            };
+            const systemPrompt = buildReviewSystemPrompt();
+            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)`,
+                status: "working",
+                currentTask: "Running Claude review",
+                progressPercent: 20,
+            });
+            // Start timeout watchdog
+            this.timeoutTimer = setTimeout(() => {
+                log.warn(this.tag, `Review timeout reached (${this.config.review.maxTimeout}ms), cancelling`);
+                this.cancel();
+            }, this.config.review.maxTimeout);
+            // 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 (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))`);
+            await this.client.updateAgentProgress(card.id, {
+                agentIdentifier: agentIdentifier(this.id),
+                agentName: `${AGENT_NAME} (Review)`,
+                status: "working",
+                currentTask: `Processing ${result.verdict} verdict`,
+                progressPercent: 80,
+            });
+            // Run review completion pipeline
+            await runReviewCompletion(this.client, card, result, this.config, cwd, this.branchName);
+        }
+        catch (err) {
+            this.state = "error";
+            const msg = err instanceof Error ? err.message : String(err);
+            log.error(this.tag, `Error reviewing #${card.short_id}: ${msg}`);
+            // End session as paused on error
+            try {
+                await this.client.endAgentSession(card.id, { status: "paused" });
+            }
+            catch {
+                // best-effort
+            }
+            // Move card out of Review to break the re-enqueue loop
+            try {
+                await moveCardToColumn(this.client, card, this.config.review.failColumn);
+                log.info(this.tag, `Moved #${card.short_id} to "${this.config.review.failColumn}" after error`);
+            }
+            catch {
+                log.warn(this.tag, "Failed to move card to fail column after error");
+            }
+        }
+        finally {
+            this.cleanup();
+            this.state = "idle";
+            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.
+     */
+    async cancel() {
+        if (!this.isActive)
+            return;
+        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);
+            if (!sigintDead) {
+                this.process.kill("SIGTERM");
+                log.debug(this.tag, "Sent SIGTERM to Claude");
+                const sigtermDead = await this.waitForExit(CANCEL_SIGTERM_TIMEOUT);
+                if (!sigtermDead) {
+                    this.process.kill("SIGKILL");
+                    log.warn(this.tag, "Sent SIGKILL to Claude");
+                }
+            }
+        }
+        // End agent session as paused
+        if (this.cardId) {
+            try {
+                await this.client.endAgentSession(this.cardId, { status: "paused" });
+            }
+            catch {
+                // best-effort
+            }
+        }
+    }
+    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 = [
+                "--output-format",
+                "stream-json",
+                "--verbose",
+                "--model",
+                this.config.claude.model,
+                "--max-turns",
+                String(this.config.claude.maxTurns),
+                "--allowedTools",
+                "Bash(readonly),Read,Glob,Grep,Agent,mcp__harmony__*",
+                ...(systemPrompt ? ["--append-system-prompt", systemPrompt] : []),
+                ...this.config.claude.additionalArgs,
+                "--",
+                prompt,
+            ];
+            log.info(this.tag, `Spawning review: claude ${args.slice(0, 5).join(" ")} ...`);
+            this.process = spawn("claude", args, {
+                cwd: this.worktreePath,
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+            // 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();
+            });
+            this.process.on("error", (err) => {
+                reject(new Error(`Failed to spawn claude: ${err.message}`));
+            });
+            this.process.on("close", (code) => {
+                this.process = null;
+                // Reconstruct text from stream parser text events
+                const stdout = textChunks.join("");
+                if (this.aborted) {
+                    resolve(stdout);
+                }
+                else if (code === 0) {
+                    resolve(stdout);
+                }
+                else {
+                    reject(new Error(`claude exited with code ${code}${stderr ? `: ${stderr.slice(0, 500)}` : ""}`));
+                }
+            });
+        });
+    }
+    waitForExit(timeout) {
+        return new Promise((resolve) => {
+            if (!this.process || this.process.killed) {
+                resolve(true);
+                return;
+            }
+            const timer = setTimeout(() => {
+                resolve(false);
+            }, timeout);
+            this.process.once("close", () => {
+                clearTimeout(timer);
+                resolve(true);
+            });
+        });
+    }
+    killDevServer() {
+        if (this.devServerProcess && !this.devServerProcess.killed) {
+            this.devServerProcess.kill("SIGTERM");
+            this.devServerProcess = null;
+            log.debug(this.tag, "Killed dev server");
+        }
+    }
+    cleanup() {
+        if (this.timeoutTimer) {
+            clearTimeout(this.timeoutTimer);
+            this.timeoutTimer = null;
+        }
+        this.killDevServer();
+        // 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);
+            }
+            catch {
+                log.warn(this.tag, "Failed to cleanup review worktree");
+            }
+        }
+        this.process = null;
+        this.cardId = null;
+        this.branchName = null;
+        this.worktreePath = null;
+        this.startedAt = null;
+    }
+}

package/dist/review-worktree.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Checkout an existing remote branch into a worktree for review.
+ * Unlike createWorktree() which creates a new branch, this checks out
+ * an existing branch that was pushed by the implementation worker.
+ */
+export declare function checkoutExistingBranch(basePath: string, branchName: string): string;
+/**
+ * Extract branch name from card description's completion summary.
+ * Looks for: Branch: `agent/...`
+ * Validates that the extracted name contains only safe characters.
+ */
+export declare function extractBranchFromDescription(description: string | null | undefined): string | null;

package/dist/review-worktree.js

@@ -0,0 +1,83 @@
+import { execFileSync, execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { log } from "./log.js";
+import { installCommand } from "./pm.js";
+import { cleanupWorktree } from "./worktree.js";
+const TAG = "review-worktree";
+/**
+ * Checkout an existing remote branch into a worktree for review.
+ * Unlike createWorktree() which creates a new branch, this checks out
+ * an existing branch that was pushed by the implementation worker.
+ */
+export function checkoutExistingBranch(basePath, branchName) {
+    const repoRoot = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+        encoding: "utf-8",
+    }).trim();
+    const worktreeDir = resolve(repoRoot, basePath, `review-${branchName}`);
+    if (existsSync(worktreeDir)) {
+        log.warn(TAG, `Review worktree already exists at ${worktreeDir}, cleaning up`);
+        cleanupWorktree(worktreeDir);
+    }
+    // Fetch latest to ensure we have the remote branch
+    try {
+        execFileSync("git", ["fetch", "origin", branchName], {
+            cwd: repoRoot,
+            stdio: "pipe",
+        });
+    }
+    catch {
+        throw new Error(`Failed to fetch remote branch: ${branchName}`);
+    }
+    // Delete stale local branch if it exists
+    try {
+        execFileSync("git", ["branch", "-D", branchName], {
+            cwd: repoRoot,
+            stdio: "pipe",
+        });
+    }
+    catch {
+        // Branch doesn't exist locally — that's fine
+    }
+    // Create worktree from the remote branch
+    log.info(TAG, `Creating review worktree: ${worktreeDir} (branch: ${branchName})`);
+    execFileSync("git", [
+        "worktree",
+        "add",
+        "--track",
+        "-b",
+        branchName,
+        worktreeDir,
+        `origin/${branchName}`,
+    ], { cwd: repoRoot, stdio: "pipe" });
+    // Install dependencies
+    log.info(TAG, "Installing dependencies in review worktree...");
+    try {
+        execSync(installCommand(), {
+            cwd: worktreeDir,
+            stdio: "pipe",
+            timeout: 60_000,
+        });
+    }
+    catch {
+        log.warn(TAG, "Install failed (may be fine if deps are hoisted)");
+    }
+    return worktreeDir;
+}
+/**
+ * Extract branch name from card description's completion summary.
+ * Looks for: Branch: `agent/...`
+ * Validates that the extracted name contains only safe characters.
+ */
+export function extractBranchFromDescription(description) {
+    if (!description)
+        return null;
+    const match = description.match(/Branch:\s*`([^`]+)`/);
+    const branch = match?.[1] ?? null;
+    // Validate branch name contains only safe git ref characters
+    if (branch && !/^[a-zA-Z0-9/_.-]+$/.test(branch)) {
+        log.warn(TAG, `Extracted branch name contains unsafe characters: ${branch}`);
+        return null;
+    }
+    return branch;
+}

package/dist/stream-parser.d.ts

@@ -0,0 +1,31 @@
+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, content: string | undefined];
+    text: [content: string];
+    result: [stopReason: string];
+    cost_update: [cost: CostUpdate];
+    parse_error: [msg: string];
+}
+export declare class StreamParser extends EventEmitter<StreamParserEvents> {
+    private buffer;
+    private attached;
+    /**
+     * Attach a readable stream (Claude CLI stdout) to the parser.
+     * Parses NDJSON lines and emits typed events.
+     * Each instance must only be attached once.
+     */
+    attach(stream: Readable): void;
+    private flush;
+    private parseLine;
+    private handleMessage;
+}

package/dist/stream-parser.js

@@ -0,0 +1,95 @@
+import { EventEmitter } from "node:events";
+import { log } from "./log.js";
+const TAG = "stream-parser";
+export class StreamParser extends EventEmitter {
+    buffer = "";
+    attached = false;
+    /**
+     * Attach a readable stream (Claude CLI stdout) to the parser.
+     * Parses NDJSON lines and emits typed events.
+     * Each instance must only be attached once.
+     */
+    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();
+        });
+        stream.on("end", () => {
+            // Process any remaining buffer
+            if (this.buffer.trim()) {
+                this.flush();
+            }
+        });
+    }
+    flush() {
+        const lines = this.buffer.split("\n");
+        // Keep incomplete last line in buffer
+        this.buffer = lines.pop() ?? "";
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            this.parseLine(trimmed);
+        }
+    }
+    parseLine(line) {
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            // Not valid JSON — skip silently (could be stray output)
+            log.debug(TAG, `Non-JSON line: ${line.slice(0, 100)}`);
+            return;
+        }
+        try {
+            this.handleMessage(msg);
+        }
+        catch (err) {
+            const errMsg = err instanceof Error ? err.message : String(err);
+            log.warn(TAG, `Error handling stream event: ${errMsg}`);
+            this.emit("parse_error", errMsg);
+        }
+    }
+    handleMessage(msg) {
+        switch (msg.type) {
+            case "assistant": {
+                if (msg.subtype === "tool_use" && msg.tool_name) {
+                    this.emit("tool_start", msg.tool_name, msg.input);
+                }
+                else if (msg.subtype === "text" && 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, msg.content);
+                }
+                break;
+            }
+            case "result": {
+                this.emit("result", msg.stop_reason ?? "unknown");
+                break;
+            }
+            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.
+        }
+    }
+}