@gethmy/agent 1.0.0 → 1.0.1

package/dist/review-worker.js

@@ -0,0 +1,302 @@
+import { execFileSync, spawn } from "node:child_process";
+import { addLabelByName, moveCardToColumn } from "./board-helpers.js";
+import { log } from "./log.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 { 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;
+    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 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);
+            if (!this.branchName) {
+                throw new Error(`No branch name found in card #${card.short_id} description. ` +
+                    "Expected: Branch: `agent/...`");
+            }
+            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",
+                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);
+            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.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 });
+            }
+            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, this.worktreePath, previewUrl, diff);
+            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);
+            // Spawn Claude CLI for review
+            const stdout = await this.spawnClaude(userPrompt, systemPrompt);
+            if (this.aborted)
+                return;
+            // --- COMPLETING ---
+            this.state = "completing";
+            log.info(this.tag, `Claude review finished for #${card.short_id}`);
+            // Kill dev server
+            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, this.worktreePath, 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);
+        }
+    }
+    /**
+     * 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}`);
+        // Kill dev server first
+        this.killDevServer();
+        // Then kill Claude process with escalating signals
+        if (this.process && !this.process.killed) {
+            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
+            }
+        }
+    }
+    spawnClaude(prompt, systemPrompt) {
+        return new Promise((resolve, reject) => {
+            const args = [
+                "--print",
+                "--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, 3).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)}`);
+                    }
+                }
+            });
+            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;
+                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
+        if (this.worktreePath && this.state === "error") {
+            try {
+                cleanupWorktree(this.worktreePath, this.branchName ?? undefined);
+            }
+            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,22 @@
+import { EventEmitter } from "node:events";
+import type { Readable } from "node:stream";
+export interface StreamParserEvents {
+    tool_start: [name: string, input: unknown];
+    tool_end: [name: string, toolUseId: string];
+    text: [content: string];
+    result: [stopReason: string];
+    error: [msg: string];
+}
+export declare class StreamParser extends EventEmitter<StreamParserEvents> {
+    private buffer;
+    private finalText;
+    get outputText(): string;
+    /**
+     * Pipe a readable stream (Claude CLI stdout) through the parser.
+     * Returns when the stream ends.
+     */
+    pipe(stream: Readable): void;
+    private flush;
+    private parseLine;
+    private handleMessage;
+}

package/dist/stream-parser.js

@@ -0,0 +1,81 @@
+import { EventEmitter } from "node:events";
+import { log } from "./log.js";
+const TAG = "stream-parser";
+export class StreamParser extends EventEmitter {
+    buffer = "";
+    finalText = "";
+    get outputText() {
+        return this.finalText;
+    }
+    /**
+     * Pipe a readable stream (Claude CLI stdout) through the parser.
+     * Returns when the stream ends.
+     */
+    pipe(stream) {
+        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("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.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);
+                }
+                break;
+            }
+            case "result": {
+                this.emit("result", msg.stop_reason ?? "unknown");
+                break;
+            }
+            // Ignore system, ping, cost_update, etc.
+        }
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,74 @@
+import type { Card, Column, Label, Subtask } from "@harmony/shared";
+export type WorkMode = "implement" | "review";
+export interface AgentConfig {
+    poolSize: number;
+    maxTimeout: number;
+    pickupColumns: string[];
+    priorityLabels: Record<string, number>;
+    columnBoost: boolean;
+    completion: {
+        createPR: boolean;
+        moveToColumn: string;
+        postSummary: boolean;
+    };
+    claude: {
+        model: string;
+        maxTurns: number;
+        additionalArgs: string[];
+    };
+    worktree: {
+        basePath: string;
+        baseBranch: string;
+    };
+    verification: {
+        enabled: boolean;
+        build: boolean;
+        lint: boolean;
+        autoFix: boolean;
+        maxFixAttempts: number;
+        deepReview: boolean;
+        devServerBasePort: number;
+        timeout: number;
+        failColumn: string;
+    };
+    review: {
+        enabled: boolean;
+        pickupColumns: string[];
+        moveToColumn: string;
+        failColumn: string;
+        devServerPort: number;
+        maxTimeout: number;
+        postFindings: boolean;
+        maxReviewCycles: number;
+        createPR: boolean;
+        approvedLabel: string;
+        approvedLabelColor: string;
+        mergeMonitor: boolean;
+        mergedLabel: string;
+        mergedLabelColor: string;
+    };
+}
+export declare const DEFAULT_AGENT_CONFIG: AgentConfig;
+export declare const AGENT_NAME = "Harmony Agent";
+export declare function agentIdentifier(workerId: number): string;
+export type ProgressPhase = "exploring" | "implementing" | "testing" | "committing" | "finishing";
+export type WorkerState = "idle" | "preparing" | "running" | "completing" | "verifying" | "cancelling" | "error";
+export interface QueueItem {
+    cardId: string;
+    shortId: number;
+    title: string;
+    priority: number;
+    enqueuedAt: number;
+    mode: WorkMode;
+}
+export interface EnrichedCard {
+    card: Card;
+    column: Column;
+    labels: Label[];
+    subtasks: Subtask[];
+    mode: WorkMode;
+}
+export interface RealtimeCredentials {
+    supabaseUrl: string;
+    supabaseAnonKey: string;
+}

package/dist/types.js

@@ -0,0 +1,53 @@
+export const DEFAULT_AGENT_CONFIG = {
+    poolSize: 1,
+    maxTimeout: 1_800_000, // 30 minutes
+    pickupColumns: ["To Do"],
+    priorityLabels: { urgent: 100, critical: 90, bug: 50 },
+    columnBoost: true,
+    completion: {
+        createPR: false,
+        moveToColumn: "Review",
+        postSummary: true,
+    },
+    claude: {
+        model: "opus",
+        maxTurns: 200,
+        additionalArgs: [],
+    },
+    worktree: {
+        basePath: ".harmony-worktrees",
+        baseBranch: "main",
+    },
+    verification: {
+        enabled: true,
+        build: true,
+        lint: true,
+        autoFix: true,
+        maxFixAttempts: 1,
+        deepReview: false,
+        devServerBasePort: 4200,
+        timeout: 120_000,
+        failColumn: "Needs Fix",
+    },
+    review: {
+        enabled: true,
+        pickupColumns: ["Review"],
+        moveToColumn: "Done",
+        failColumn: "To Do",
+        devServerPort: 4300,
+        maxTimeout: 600_000,
+        postFindings: true,
+        maxReviewCycles: 3,
+        createPR: true,
+        approvedLabel: "Ready to Merge",
+        approvedLabelColor: "#22c55e",
+        mergeMonitor: true,
+        mergedLabel: "Merged",
+        mergedLabelColor: "#6366f1",
+    },
+};
+// ============ AGENT IDENTITY ============
+export const AGENT_NAME = "Harmony Agent";
+export function agentIdentifier(workerId) {
+    return `harmony-daemon-${workerId}`;
+}

package/dist/verification.d.ts

@@ -0,0 +1,16 @@
+import { type ChildProcess } from "node:child_process";
+import type { HarmonyApiClient } from "@gethmy/mcp/src/api-client.js";
+import type { AgentConfig } from "./types.js";
+export interface VerificationResult {
+    passed: boolean;
+    buildErrors: string[];
+    lintWarnings: string[];
+    reviewFindings: string[];
+}
+export declare function runVerification(worktreePath: string, config: AgentConfig, workerId: number): Promise<VerificationResult>;
+export declare function runBuild(worktreePath: string, timeout: number): string[];
+export declare function runLint(worktreePath: string, timeout: number): string[];
+export declare function runDeepReview(worktreePath: string, config: AgentConfig, workerId: number): Promise<string[]>;
+export declare function attemptAutoFix(worktreePath: string, config: AgentConfig, errors: string[]): void;
+export declare function reportFindings(client: HarmonyApiClient, cardId: string, result: VerificationResult): Promise<void>;
+export declare function waitForDevServer(proc: ChildProcess, timeout: number): Promise<void>;