@gethmy/agent 1.0.0 → 1.0.1

package/dist/verification.js

@@ -0,0 +1,251 @@
+import { execFileSync, spawn } from "node:child_process";
+import { log } from "./log.js";
+import { spawnRunArgs } from "./pm.js";
+const TAG = "verification";
+// ============ PUBLIC API ============
+export async function runVerification(worktreePath, config, workerId) {
+    const result = {
+        passed: true,
+        buildErrors: [],
+        lintWarnings: [],
+        reviewFindings: [],
+    };
+    if (config.verification.build) {
+        log.info(TAG, `[worker:${workerId}] Running build...`);
+        result.buildErrors = runBuild(worktreePath, config.verification.timeout);
+        if (result.buildErrors.length > 0) {
+            log.warn(TAG, `[worker:${workerId}] Build failed with ${result.buildErrors.length} error(s)`);
+            result.passed = false;
+        }
+        else {
+            log.info(TAG, `[worker:${workerId}] Build passed`);
+        }
+    }
+    if (config.verification.lint) {
+        log.info(TAG, `[worker:${workerId}] Running lint...`);
+        result.lintWarnings = runLint(worktreePath, config.verification.timeout);
+        if (result.lintWarnings.length > 0) {
+            log.warn(TAG, `[worker:${workerId}] Lint found ${result.lintWarnings.length} issue(s)`);
+            // Lint warnings alone don't block — only build errors block
+        }
+        else {
+            log.info(TAG, `[worker:${workerId}] Lint passed`);
+        }
+    }
+    if (config.verification.deepReview) {
+        log.info(TAG, `[worker:${workerId}] Running deep review...`);
+        result.reviewFindings = await runDeepReview(worktreePath, config, workerId);
+        if (result.reviewFindings.length > 0) {
+            log.warn(TAG, `[worker:${workerId}] Deep review found ${result.reviewFindings.length} finding(s)`);
+        }
+        else {
+            log.info(TAG, `[worker:${workerId}] Deep review passed`);
+        }
+    }
+    return result;
+}
+export function runBuild(worktreePath, timeout) {
+    try {
+        const [cmd, args] = spawnRunArgs("build");
+        execFileSync(cmd, args, {
+            cwd: worktreePath,
+            timeout,
+            stdio: "pipe",
+        });
+        return [];
+    }
+    catch (err) {
+        return parseErrorOutput(err);
+    }
+}
+export function runLint(worktreePath, timeout) {
+    try {
+        const [cmd, args] = spawnRunArgs("lint");
+        execFileSync(cmd, args, {
+            cwd: worktreePath,
+            timeout,
+            stdio: "pipe",
+        });
+        return [];
+    }
+    catch (err) {
+        return parseErrorOutput(err);
+    }
+}
+export async function runDeepReview(worktreePath, config, workerId) {
+    const port = config.verification.devServerBasePort + workerId;
+    let devServer = null;
+    try {
+        // Start dev server in background
+        const [cmd, args] = spawnRunArgs("dev", "--port", String(port));
+        devServer = spawn(cmd, args, {
+            cwd: worktreePath,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        // Wait for dev server to be ready
+        await waitForDevServer(devServer, 30_000);
+        // Get diff for review context
+        let diff = "";
+        try {
+            diff = execFileSync("git", ["diff", `origin/${config.worktree.baseBranch}..HEAD`], { cwd: worktreePath, encoding: "utf-8", timeout: 30_000 });
+        }
+        catch {
+            diff = "(unable to retrieve diff)";
+        }
+        // Spawn Claude for review
+        const reviewPrompt = [
+            "You are reviewing code changes for quality and correctness.",
+            `A dev server is running at http://localhost:${port}.`,
+            "Review the following diff and report any issues found.",
+            "Output ONLY a numbered list of findings, one per line.",
+            "If no issues, output: No issues found.",
+            "",
+            "```diff",
+            diff.slice(0, 50_000),
+            "```",
+        ].join("\n");
+        const output = execFileSync("claude", ["--print", "--model", "sonnet", "--max-turns", "10", "--", reviewPrompt], {
+            cwd: worktreePath,
+            encoding: "utf-8",
+            timeout: config.verification.timeout,
+            stdio: "pipe",
+        });
+        return parseReviewFindings(output);
+    }
+    catch (err) {
+        log.error(TAG, `Deep review failed: ${err instanceof Error ? err.message : err}`);
+        return [];
+    }
+    finally {
+        if (devServer && !devServer.killed) {
+            devServer.kill("SIGTERM");
+        }
+    }
+}
+export function attemptAutoFix(worktreePath, config, errors) {
+    const errorSummary = errors.slice(0, 20).join("\n");
+    const fixPrompt = [
+        "The following build/lint errors were found after implementing a feature.",
+        "Fix the source files to resolve these errors.",
+        "Do NOT commit build artifacts or modify files in dist/.",
+        "Fix source files only.",
+        "",
+        "Errors:",
+        "```",
+        errorSummary,
+        "```",
+    ].join("\n");
+    const args = [
+        "--print",
+        "--model",
+        config.claude.model,
+        "--max-turns",
+        "50",
+        "--allowedTools",
+        "Bash,Read,Write,Edit,Glob,Grep",
+        "--",
+        fixPrompt,
+    ];
+    log.info(TAG, "Spawning Claude for auto-fix...");
+    execFileSync("claude", args, {
+        cwd: worktreePath,
+        timeout: config.verification.timeout,
+        stdio: "pipe",
+    });
+}
+export async function reportFindings(client, cardId, result) {
+    const items = [];
+    for (const err of result.buildErrors) {
+        items.push(`Build: ${err}`);
+    }
+    for (const err of result.lintWarnings) {
+        items.push(`Lint: ${err}`);
+    }
+    for (const finding of result.reviewFindings) {
+        items.push(`Review: ${finding}`);
+    }
+    const maxSubtasks = 10;
+    const overflow = items.length - maxSubtasks;
+    const toCreate = items.slice(0, maxSubtasks);
+    await Promise.all(toCreate.map(async (item) => {
+        const title = item.length > 120 ? `${item.slice(0, 117)}...` : item;
+        try {
+            await client.createSubtask(cardId, title);
+        }
+        catch (err) {
+            log.error(TAG, `Failed to create subtask: ${err instanceof Error ? err.message : err}`);
+        }
+    }));
+    if (overflow > 0) {
+        try {
+            await client.createSubtask(cardId, `...and ${overflow} more issues`);
+        }
+        catch {
+            // best-effort
+        }
+    }
+    log.info(TAG, `Reported ${Math.min(items.length, maxSubtasks)} finding(s) as subtasks on card ${cardId}`);
+}
+// ============ HELPERS ============
+function parseErrorOutput(err) {
+    const stderr = err?.stderr?.toString() ?? "";
+    const stdout = err?.stdout?.toString() ?? "";
+    const combined = `${stderr}\n${stdout}`;
+    const lines = combined
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0 &&
+        (l.includes("error") ||
+            l.includes("Error") ||
+            l.includes("✖") ||
+            l.includes("×")))
+        .map((l) => (l.length > 200 ? `${l.slice(0, 197)}...` : l));
+    // If we couldn't parse specific error lines, return the whole output truncated
+    if (lines.length === 0 && combined.trim().length > 0) {
+        return [combined.trim().slice(0, 200)];
+    }
+    return lines;
+}
+function parseReviewFindings(output) {
+    if (output.toLowerCase().includes("no issues found")) {
+        return [];
+    }
+    return output
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => /^\d+[.)]/.test(l))
+        .map((l) => l.replace(/^\d+[.)]\s*/, ""))
+        .filter((l) => l.length > 0);
+}
+export function waitForDevServer(proc, timeout) {
+    return new Promise((resolve, reject) => {
+        const cleanup = () => {
+            proc.stdout?.off("data", onData);
+            proc.stderr?.off("data", onData);
+            proc.off("error", onError);
+        };
+        const timer = setTimeout(() => {
+            log.warn(TAG, "Dev server readiness not detected, proceeding anyway");
+            cleanup();
+            resolve();
+        }, timeout);
+        const onData = (data) => {
+            const text = data.toString();
+            if (text.includes("ready") ||
+                text.includes("localhost") ||
+                text.includes("Local:")) {
+                clearTimeout(timer);
+                cleanup();
+                resolve();
+            }
+        };
+        const onError = (err) => {
+            clearTimeout(timer);
+            cleanup();
+            reject(err);
+        };
+        proc.stdout?.on("data", onData);
+        proc.stderr?.on("data", onData);
+        proc.on("error", onError);
+    });
+}

package/dist/watcher.d.ts

@@ -0,0 +1,21 @@
+import type { RealtimeCredentials } from "./types.js";
+export interface CardBroadcastEvent {
+    event: "card_update" | "card_created";
+    payload: Record<string, unknown>;
+}
+export type CardBroadcastHandler = (event: CardBroadcastEvent) => void;
+/**
+ * Subscribes to Supabase broadcast events on the board channel.
+ * The harmony-api broadcasts card_update and card_created events
+ * after every mutation — this works with the anon key (no RLS needed).
+ */
+export declare class Watcher {
+    private credentials;
+    private projectId;
+    private onCardBroadcast;
+    private channel;
+    private supabase;
+    constructor(credentials: RealtimeCredentials, projectId: string, onCardBroadcast: CardBroadcastHandler);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}

package/dist/watcher.js

@@ -0,0 +1,62 @@
+import { createClient } from "@supabase/supabase-js";
+import { log } from "./log.js";
+const TAG = "watcher";
+/**
+ * Subscribes to Supabase broadcast events on the board channel.
+ * The harmony-api broadcasts card_update and card_created events
+ * after every mutation — this works with the anon key (no RLS needed).
+ */
+export class Watcher {
+    credentials;
+    projectId;
+    onCardBroadcast;
+    channel = null;
+    supabase = null;
+    constructor(credentials, projectId, onCardBroadcast) {
+        this.credentials = credentials;
+        this.projectId = projectId;
+        this.onCardBroadcast = onCardBroadcast;
+    }
+    async start() {
+        log.info(TAG, "Connecting to Supabase realtime (broadcast)...");
+        this.supabase = createClient(this.credentials.supabaseUrl, this.credentials.supabaseAnonKey);
+        this.channel = this.supabase
+            .channel(`board-${this.projectId}`)
+            .on("broadcast", { event: "card_update" }, (msg) => {
+            log.debug(TAG, `Broadcast: card_update ${JSON.stringify(msg.payload)}`);
+            this.onCardBroadcast({
+                event: "card_update",
+                payload: msg.payload ?? {},
+            });
+        })
+            .on("broadcast", { event: "card_created" }, (msg) => {
+            log.debug(TAG, `Broadcast: card_created ${JSON.stringify(msg.payload)}`);
+            this.onCardBroadcast({
+                event: "card_created",
+                payload: msg.payload ?? {},
+            });
+        })
+            .subscribe((status) => {
+            if (status === "SUBSCRIBED") {
+                log.info(TAG, "Broadcast subscription active");
+            }
+            else if (status === "CHANNEL_ERROR") {
+                log.error(TAG, "Broadcast channel error — will rely on reconciliation");
+            }
+            else if (status === "TIMED_OUT") {
+                log.warn(TAG, "Broadcast subscription timed out — retrying...");
+            }
+        });
+    }
+    async stop() {
+        if (this.channel) {
+            await this.supabase?.removeChannel(this.channel);
+            this.channel = null;
+        }
+        if (this.supabase) {
+            await this.supabase.realtime.disconnect();
+            this.supabase = null;
+        }
+        log.info(TAG, "Broadcast subscription stopped");
+    }
+}

package/dist/worker.d.ts

@@ -0,0 +1,34 @@
+import type { HarmonyApiClient } from "@gethmy/mcp/src/api-client.js";
+import type { Card, Column, Label, Subtask } from "@harmony/shared";
+import { type AgentConfig, type WorkerState } from "./types.js";
+export declare class Worker {
+    private config;
+    private client;
+    private onDone;
+    id: number;
+    state: WorkerState;
+    cardId: string | null;
+    branchName: string | null;
+    worktreePath: string | null;
+    startedAt: number | null;
+    private process;
+    private timeoutTimer;
+    private progressTracker;
+    private aborted;
+    constructor(id: number, config: AgentConfig, client: HarmonyApiClient, _userEmail: string, onDone: (worker: Worker) => void);
+    get tag(): string;
+    get isIdle(): boolean;
+    get isActive(): boolean;
+    /**
+     * Start working on a card. Runs the full lifecycle:
+     * PREPARING → RUNNING → COMPLETING → IDLE
+     */
+    run(card: Card, column: Column, labels: Label[], subtasks: Subtask[]): Promise<void>;
+    /**
+     * Cancel the current work. Sends escalating signals to the Claude process.
+     */
+    cancel(): Promise<void>;
+    private spawnClaude;
+    private waitForExit;
+    private cleanup;
+}

package/dist/worker.js

@@ -0,0 +1,268 @@
+import { spawn } from "node:child_process";
+import { moveCardAndAddLabel } from "./board-helpers.js";
+import { runCompletion } from "./completion.js";
+import { log } from "./log.js";
+import { ProgressTracker } from "./progress-tracker.js";
+import { buildPrompt } from "./prompt.js";
+import { StreamParser } from "./stream-parser.js";
+import { AGENT_NAME, agentIdentifier, } from "./types.js";
+import { cleanupWorktree, createWorktree, makeBranchName } from "./worktree.js";
+const TAG = "worker";
+const CANCEL_SIGINT_TIMEOUT = 30_000;
+const CANCEL_SIGTERM_TIMEOUT = 10_000;
+export class Worker {
+    config;
+    client;
+    onDone;
+    id;
+    state = "idle";
+    cardId = null;
+    branchName = null;
+    worktreePath = null;
+    startedAt = null;
+    process = 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 isActive() {
+        return (this.state === "preparing" ||
+            this.state === "running" ||
+            this.state === "verifying" ||
+            this.state === "completing");
+    }
+    /**
+     * Start working on a card. Runs the full lifecycle:
+     * PREPARING → RUNNING → COMPLETING → IDLE
+     */
+    async run(card, column, labels, subtasks) {
+        this.aborted = false;
+        this.cardId = card.id;
+        this.startedAt = Date.now();
+        try {
+            // --- PREPARING ---
+            this.state = "preparing";
+            this.branchName = makeBranchName(card.short_id, card.title);
+            log.info(this.tag, `Preparing #${card.short_id} "${card.title}"`);
+            // Start agent session and make it visible on the board
+            await this.client.startAgentSession(card.id, {
+                agentIdentifier: agentIdentifier(this.id),
+                agentName: AGENT_NAME,
+                status: "working",
+                currentTask: "Setting up worktree",
+                progressPercent: 5,
+            });
+            // Move card to "In Progress" and add "agent" label so the board shows the progress ring
+            const moved = await moveCardAndAddLabel(this.client, card, "In Progress", "agent");
+            if (!moved) {
+                log.warn(this.tag, `Card #${card.short_id} was NOT moved to "In Progress" — check API logs`);
+            }
+            if (this.aborted)
+                return;
+            // Create worktree
+            this.worktreePath = createWorktree(this.config.worktree.basePath, this.config.worktree.baseBranch, this.branchName);
+            if (this.aborted)
+                return;
+            // --- RUNNING ---
+            this.state = "running";
+            const enriched = {
+                card,
+                column,
+                labels,
+                subtasks,
+                mode: "implement",
+            };
+            const prompt = buildPrompt(enriched, this.branchName, this.worktreePath);
+            await this.client.updateAgentProgress(card.id, {
+                agentIdentifier: agentIdentifier(this.id),
+                agentName: AGENT_NAME,
+                status: "working",
+                currentTask: "Running Claude CLI",
+                progressPercent: 10,
+            });
+            // Start timeout watchdog
+            this.timeoutTimer = setTimeout(() => {
+                log.warn(this.tag, `Timeout reached (${this.config.maxTimeout}ms), cancelling`);
+                this.cancel();
+            }, this.config.maxTimeout);
+            // Spawn Claude CLI
+            await this.spawnClaude(prompt, card, subtasks);
+            if (this.aborted)
+                return;
+            // --- VERIFYING + COMPLETING ---
+            this.state = "verifying";
+            log.info(this.tag, `Claude finished for #${card.short_id}, running verification & completion`);
+            await this.client.updateAgentProgress(card.id, {
+                agentIdentifier: agentIdentifier(this.id),
+                agentName: AGENT_NAME,
+                status: "working",
+                currentTask: "Verifying implementation",
+                progressPercent: 75,
+            });
+            this.state = "completing";
+            await runCompletion(this.client, card, this.branchName, this.worktreePath, this.config, this.id);
+        }
+        catch (err) {
+            this.state = "error";
+            const msg = err instanceof Error ? err.message : String(err);
+            log.error(this.tag, `Error on #${card.short_id}: ${msg}`);
+            // End session as paused on error
+            try {
+                await this.client.endAgentSession(card.id, {
+                    status: "paused",
+                });
+            }
+            catch {
+                // best-effort
+            }
+        }
+        finally {
+            this.cleanup();
+            this.state = "idle";
+            this.onDone(this);
+        }
+    }
+    /**
+     * Cancel the current work. Sends escalating signals to the Claude process.
+     */
+    async cancel() {
+        if (!this.isActive)
+            return;
+        this.aborted = true;
+        this.state = "cancelling";
+        log.info(this.tag, `Cancelling work on ${this.cardId}`);
+        if (this.process && !this.process.killed) {
+            // Step 1: SIGINT (let Claude save state gracefully)
+            this.process.kill("SIGINT");
+            log.debug(this.tag, "Sent SIGINT");
+            const sigintDead = await this.waitForExit(CANCEL_SIGINT_TIMEOUT);
+            if (sigintDead)
+                return;
+            // Step 2: SIGTERM
+            this.process.kill("SIGTERM");
+            log.debug(this.tag, "Sent SIGTERM");
+            const sigtermDead = await this.waitForExit(CANCEL_SIGTERM_TIMEOUT);
+            if (sigtermDead)
+                return;
+            // Step 3: SIGKILL
+            this.process.kill("SIGKILL");
+            log.warn(this.tag, "Sent SIGKILL");
+        }
+        // End agent session as paused
+        if (this.cardId) {
+            try {
+                await this.client.endAgentSession(this.cardId, { status: "paused" });
+            }
+            catch {
+                // best-effort
+            }
+        }
+    }
+    async spawnClaude(prompt, card, subtasks) {
+        return new Promise((resolve, reject) => {
+            const args = [
+                "-p",
+                "--verbose", // required for stream-json to emit all event types
+                "--output-format",
+                "stream-json",
+                "--model",
+                this.config.claude.model,
+                "--max-turns",
+                String(this.config.claude.maxTurns),
+                "--allowedTools",
+                "Bash,Read,Write,Edit,Glob,Grep,Agent,mcp__harmony__*",
+                ...this.config.claude.additionalArgs,
+                "--",
+                prompt,
+            ];
+            log.info(this.tag, `Spawning: claude ${args.slice(0, 4).join(" ")} ...`);
+            this.process = spawn("claude", args, {
+                cwd: this.worktreePath,
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+            // Stream parser for structured NDJSON events
+            const parser = new StreamParser();
+            // Progress tracker for phase-based updates
+            this.progressTracker = new ProgressTracker(this.client, card.id, this.id, subtasks);
+            this.progressTracker.attach(parser);
+            // Pipe stdout through parser
+            if (this.process.stdout) {
+                parser.pipe(this.process.stdout);
+            }
+            parser.on("error", (msg) => {
+                log.debug(this.tag, `Stream parse error (non-fatal): ${msg}`);
+            });
+            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;
+                this.progressTracker?.stop();
+                this.progressTracker = null;
+                if (this.aborted) {
+                    resolve(); // Cancellation is not an error
+                }
+                else if (code === 0) {
+                    resolve();
+                }
+                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);
+            });
+        });
+    }
+    cleanup() {
+        if (this.progressTracker) {
+            this.progressTracker.stop();
+            this.progressTracker = null;
+        }
+        if (this.timeoutTimer) {
+            clearTimeout(this.timeoutTimer);
+            this.timeoutTimer = null;
+        }
+        // Clean up worktree + branch on error
+        if (this.worktreePath && this.state === "error") {
+            try {
+                cleanupWorktree(this.worktreePath, this.branchName ?? undefined);
+            }
+            catch {
+                log.warn(this.tag, "Failed to cleanup worktree");
+            }
+        }
+        this.process = null;
+        this.cardId = null;
+        this.branchName = null;
+        this.worktreePath = null;
+        this.startedAt = null;
+    }
+}

package/dist/worktree.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Create a git worktree for the agent to work in.
+ * Returns the absolute path to the new worktree.
+ */
+export declare function createWorktree(basePath: string, baseBranch: string, branchName: string): string;
+/**
+ * Remove a git worktree and its branch.
+ */
+export declare function cleanupWorktree(worktreePath: string, branchName?: string): void;
+/**
+ * Generate a branch name from a card's short ID and title.
+ */
+export declare function makeBranchName(shortId: number, title: string): string;