@gethmy/agent 1.0.0 → 1.0.2

package/dist/types.d.ts

@@ -0,0 +1,76 @@
+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 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";
+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,56 @@
+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",
+    },
+};
+// ============ 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) {
+    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>;

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,27 @@
+import type { RealtimeCredentials } from "./types.js";
+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
+ * after every mutation — this works with the anon key (no RLS needed).
+ */
+export declare class Watcher {
+    private credentials;
+    private projectId;
+    private onCardBroadcast;
+    private onAgentCommand?;
+    private channel;
+    private supabase;
+    constructor(credentials: RealtimeCredentials, projectId: string, onCardBroadcast: CardBroadcastHandler, onAgentCommand?: AgentCommandHandler | undefined);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}

package/dist/watcher.js

@@ -0,0 +1,74 @@
+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;
+    onAgentCommand;
+    channel = null;
+    supabase = null;
+    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);
+        const 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 ?? {},
+            });
+        })
+            .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") {
+                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...");
+            }
+        });
+        this.channel = channel;
+    }
+    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,43 @@
+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 lastSessionStats;
+    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>;
+    /**
+     * 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.
+     */
+    cancel(): Promise<void>;
+    private spawnClaude;
+    private waitForExit;
+    private cleanup;
+}