@gethmy/agent 1.0.0 → 1.0.2

package/dist/worker.js

@@ -0,0 +1,327 @@
+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;
+    lastSessionStats;
+    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, this.lastSessionStats);
+        }
+        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);
+        }
+    }
+    /**
+     * Pause the current work by suspending the Claude process (SIGSTOP).
+     */
+    async pause() {
+        if (!this.isActive || !this.process || this.process.killed)
+            return;
+        log.info(this.tag, `Pausing work on ${this.cardId}`);
+        this.process.kill("SIGSTOP");
+        // Pause the timeout timer
+        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 work on ${this.cardId}`);
+        this.process.kill("SIGCONT");
+        // Restart timeout timer with remaining time (use full timeout for simplicity)
+        this.timeoutTimer = setTimeout(() => {
+            log.warn(this.tag, `Timeout reached (${this.config.maxTimeout}ms), cancelling`);
+            this.cancel();
+        }, this.config.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 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) {
+            // Resume first in case the process is suspended
+            this.process.kill("SIGCONT");
+            // 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);
+            // Attach stdout to parser
+            if (this.process.stdout) {
+                parser.attach(this.process.stdout);
+            }
+            parser.on("parse_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.lastSessionStats = this.progressTracker?.stats;
+                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;
+        }
+        this.lastSessionStats = undefined;
+        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;

package/dist/worktree.js

@@ -0,0 +1,115 @@
+import { execFileSync, execSync } from "node:child_process";
+import { existsSync, rmSync } from "node:fs";
+import { resolve } from "node:path";
+import { log } from "./log.js";
+import { installCommand } from "./pm.js";
+const TAG = "worktree";
+/**
+ * Create a git worktree for the agent to work in.
+ * Returns the absolute path to the new worktree.
+ */
+export function createWorktree(basePath, baseBranch, branchName) {
+    const repoRoot = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+        encoding: "utf-8",
+    }).trim();
+    const worktreeDir = resolve(repoRoot, basePath, branchName);
+    if (existsSync(worktreeDir)) {
+        log.warn(TAG, `Worktree already exists at ${worktreeDir}, cleaning up`);
+        cleanupWorktree(worktreeDir);
+    }
+    // Fetch latest from remote to ensure base branch is up to date
+    try {
+        execFileSync("git", ["fetch", "origin", baseBranch], {
+            cwd: repoRoot,
+            stdio: "pipe",
+        });
+    }
+    catch {
+        log.warn(TAG, "Failed to fetch latest — continuing with local state");
+    }
+    // Delete stale branch if it exists from a previous run
+    try {
+        execFileSync("git", ["branch", "-D", branchName], {
+            cwd: repoRoot,
+            stdio: "pipe",
+        });
+        log.info(TAG, `Deleted stale branch: ${branchName}`);
+    }
+    catch {
+        // Branch doesn't exist — that's fine
+    }
+    // Create worktree with a new branch based on origin/<baseBranch>
+    log.info(TAG, `Creating worktree: ${worktreeDir} (branch: ${branchName})`);
+    execFileSync("git", ["worktree", "add", "-b", branchName, worktreeDir, `origin/${baseBranch}`], { cwd: repoRoot, stdio: "pipe" });
+    // Install dependencies in the worktree
+    log.info(TAG, "Installing dependencies in 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;
+}
+/**
+ * Remove a git worktree and its branch.
+ */
+export function cleanupWorktree(worktreePath, branchName) {
+    const repoRoot = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+        encoding: "utf-8",
+    }).trim();
+    try {
+        execFileSync("git", ["worktree", "remove", worktreePath, "--force"], {
+            cwd: repoRoot,
+            stdio: "pipe",
+        });
+        log.info(TAG, `Removed worktree: ${worktreePath}`);
+    }
+    catch (err) {
+        log.warn(TAG, `Failed to remove worktree cleanly: ${err instanceof Error ? err.message : err}`);
+        // Force-remove the directory if git worktree remove failed
+        if (existsSync(worktreePath)) {
+            rmSync(worktreePath, { recursive: true, force: true });
+        }
+        // Prune stale worktree entries
+        try {
+            execFileSync("git", ["worktree", "prune"], {
+                cwd: repoRoot,
+                stdio: "pipe",
+            });
+        }
+        catch {
+            // best-effort
+        }
+    }
+    // Delete the branch so it doesn't block future runs
+    if (branchName) {
+        try {
+            execFileSync("git", ["branch", "-D", branchName], {
+                cwd: repoRoot,
+                stdio: "pipe",
+            });
+        }
+        catch {
+            // best-effort
+        }
+    }
+}
+/**
+ * Generate a branch name from a card's short ID and title.
+ */
+export function makeBranchName(shortId, title) {
+    const slug = title
+        .toLowerCase()
+        .trim()
+        .replace(/[^\w\s-]/g, "")
+        .replace(/\s+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 40);
+    return `agent/${shortId}-${slug || "task"}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/agent",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Push-based agent daemon for Harmony — watches board assignments and spawns Claude CLI workers",
   "type": "module",
   "main": "dist/index.js",
@@ -32,21 +32,22 @@
     "automation"
   ],
   "engines": {
+    "node": ">=20.0.0",
     "bun": ">=1.0.0"
   },
   "scripts": {
-    "start": "bun src/index.ts",
-    "build": "bun build src/index.ts src/cli.ts --outdir dist --target bun",
+    "start": "node dist/index.js",
+    "build": "tsc",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "bun run build"
+    "prepublishOnly": "npm run build"
   },
   "dependencies": {
     "@supabase/supabase-js": "2.95.3",
-    "@gethmy/mcp": "workspace:*"
+    "@gethmy/mcp": "^2.0.0"
   },
   "devDependencies": {
     "@harmony/shared": "workspace:*",
-    "@types/node": "^25.2.0",
-    "typescript": "^5.9.3"
+    "@types/node": "^25.5.0",
+    "typescript": "^6.0.1"
   }
 }