@gethmy/agent 1.0.0 → 1.0.1

package/dist/progress-tracker.js

@@ -0,0 +1,189 @@
+import { log } from "./log.js";
+import { AGENT_NAME, agentIdentifier } from "./types.js";
+const TAG = "progress-tracker";
+const THROTTLE_MS = 5_000;
+const HEARTBEAT_MS = 60_000;
+const PHASES = {
+    exploring: { min: 10, max: 25, task: "Reading codebase..." },
+    implementing: { min: 25, max: 55, task: "Implementing changes..." },
+    testing: { min: 55, max: 65, task: "Running tests..." },
+    committing: { min: 65, max: 70, task: "Committing changes..." },
+    finishing: { min: 70, max: 75, task: "Finalizing..." },
+};
+// Tools that indicate exploring phase
+const _EXPLORE_TOOLS = new Set(["Read", "Glob", "Grep", "Agent"]);
+// Tools that indicate implementation
+const EDIT_TOOLS = new Set(["Write", "Edit", "MultiEdit", "NotebookEdit"]);
+export class ProgressTracker {
+    client;
+    cardId;
+    workerId;
+    phase = "exploring";
+    progress = 10;
+    toolCallCount = 0;
+    hasEdited = false;
+    lastUpdateAt = 0;
+    pendingUpdate = null;
+    heartbeatTimer = null;
+    stopped = false;
+    // Subtask tracking
+    subtaskTotal;
+    subtaskCompleted;
+    subtaskMode;
+    constructor(client, cardId, workerId, subtasks) {
+        this.client = client;
+        this.cardId = cardId;
+        this.workerId = workerId;
+        this.subtaskTotal = subtasks.length;
+        this.subtaskCompleted = subtasks.filter((s) => s.completed).length;
+        this.subtaskMode = subtasks.length > 0;
+    }
+    /**
+     * Wire up the parser events and start the heartbeat.
+     */
+    attach(parser) {
+        parser.on("tool_start", (name, input) => {
+            this.onToolStart(name, input);
+        });
+        parser.on("tool_end", (name) => {
+            this.onToolEnd(name);
+        });
+        this.startHeartbeat();
+    }
+    /**
+     * Stop all timers and flush any pending update.
+     */
+    stop() {
+        this.stopped = true;
+        if (this.pendingUpdate) {
+            clearTimeout(this.pendingUpdate);
+            this.pendingUpdate = null;
+        }
+        if (this.heartbeatTimer) {
+            clearTimeout(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+    }
+    onToolStart(name, input) {
+        this.toolCallCount++;
+        log.debug(TAG, `Tool: ${name} (count: ${this.toolCallCount}, phase: ${this.phase})`);
+        // Detect phase transitions
+        if (!this.hasEdited && EDIT_TOOLS.has(name)) {
+            this.hasEdited = true;
+            this.transitionTo("implementing");
+        }
+        else if (this.hasEdited && name === "Bash") {
+            const cmd = this.extractBashCommand(input);
+            if (cmd && /\bgit\s+commit\b/.test(cmd)) {
+                this.transitionTo("committing");
+            }
+            else if (cmd &&
+                /\b(test|build|lint|check|tsc|vitest|jest|(?:bun|npm|pnpm|yarn) run (?:build|lint))\b/.test(cmd)) {
+                this.transitionTo("testing");
+            }
+        }
+        else if (name.startsWith("mcp__harmony__harmony_end_agent_session")) {
+            this.transitionTo("finishing");
+        }
+        // Handle subtask toggling — override heuristic progress
+        if (name === "mcp__harmony__harmony_toggle_subtask" && this.subtaskMode) {
+            this.subtaskCompleted = Math.min(this.subtaskCompleted + 1, this.subtaskTotal);
+            const subtaskProgress = Math.round(10 + (this.subtaskCompleted / this.subtaskTotal) * 60);
+            this.progress = Math.max(this.progress, subtaskProgress);
+            this.scheduleUpdate(`Completed subtask ${this.subtaskCompleted}/${this.subtaskTotal}`);
+            return;
+        }
+        // Increment progress within current phase bounds
+        this.incrementProgress();
+    }
+    onToolEnd(_name) {
+        // Reset heartbeat on any activity
+        this.startHeartbeat();
+    }
+    transitionTo(newPhase) {
+        if (this.phaseOrder(newPhase) <= this.phaseOrder(this.phase))
+            return;
+        log.info(TAG, `Phase: ${this.phase} → ${newPhase}`);
+        this.phase = newPhase;
+        this.progress = Math.max(this.progress, PHASES[newPhase].min);
+        this.scheduleUpdate(PHASES[newPhase].task);
+    }
+    incrementProgress() {
+        const config = PHASES[this.phase];
+        const range = config.max - config.min;
+        // Each tool call moves ~2% within the phase, so roughly 7-15 calls fill a phase
+        const step = Math.max(1, Math.round(range / 12));
+        const newProgress = Math.min(this.progress + step, config.max);
+        if (newProgress > this.progress) {
+            this.progress = newProgress;
+            this.scheduleUpdate(this.currentTaskLabel());
+        }
+    }
+    currentTaskLabel() {
+        const config = PHASES[this.phase];
+        return config.task;
+    }
+    scheduleUpdate(currentTask) {
+        if (this.stopped)
+            return;
+        const now = Date.now();
+        const elapsed = now - this.lastUpdateAt;
+        if (elapsed >= THROTTLE_MS) {
+            // Can send immediately
+            this.sendUpdate(currentTask);
+        }
+        else if (!this.pendingUpdate) {
+            // Schedule for after throttle window
+            const delay = THROTTLE_MS - elapsed;
+            this.pendingUpdate = setTimeout(() => {
+                this.pendingUpdate = null;
+                if (!this.stopped) {
+                    this.sendUpdate(currentTask);
+                }
+            }, delay);
+        }
+        // If there's already a pending update, it will fire soon — skip
+    }
+    sendUpdate(currentTask) {
+        this.lastUpdateAt = Date.now();
+        log.debug(TAG, `Progress: ${this.progress}% — ${currentTask}`);
+        this.client
+            .updateAgentProgress(this.cardId, {
+            agentIdentifier: agentIdentifier(this.workerId),
+            agentName: AGENT_NAME,
+            status: "working",
+            currentTask,
+            progressPercent: this.progress,
+        })
+            .catch((err) => {
+            log.warn(TAG, `Failed to send progress update: ${err}`);
+        });
+    }
+    startHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearTimeout(this.heartbeatTimer);
+        }
+        this.heartbeatTimer = setTimeout(() => {
+            if (!this.stopped) {
+                this.sendUpdate("Still working...");
+                this.startHeartbeat();
+            }
+        }, HEARTBEAT_MS);
+    }
+    phaseOrder(phase) {
+        const order = [
+            "exploring",
+            "implementing",
+            "testing",
+            "committing",
+            "finishing",
+        ];
+        return order.indexOf(phase);
+    }
+    extractBashCommand(input) {
+        if (typeof input === "object" && input !== null && "command" in input) {
+            return String(input.command);
+        }
+        return null;
+    }
+}

package/dist/prompt.d.ts

@@ -0,0 +1,5 @@
+import type { EnrichedCard } from "./types.js";
+/**
+ * Build the prompt that gets passed to Claude CLI for working on a card.
+ */
+export declare function buildPrompt(enriched: EnrichedCard, branchName: string, worktreePath: string): string;

package/dist/prompt.js

@@ -0,0 +1,40 @@
+/**
+ * Build the prompt that gets passed to Claude CLI for working on a card.
+ */
+export function buildPrompt(enriched, branchName, worktreePath) {
+    const { card, column, labels, subtasks } = enriched;
+    const labelStr = labels.length > 0 ? labels.map((l) => l.name).join(", ") : "none";
+    const subtaskStr = subtasks.length > 0
+        ? subtasks
+            .map((s) => `- [${s.completed ? "x" : " "}] ${s.title}`)
+            .join("\n")
+        : "No subtasks defined.";
+    const description = card.description?.trim() || "No description provided.";
+    return `You are an AI agent working on a task from the Harmony project board.
+
+## Card: #${card.short_id} - ${card.title}
+**Labels**: ${labelStr}
+**Column**: ${column.name}
+**Priority**: ${card.priority}
+
+## Description
+${description}
+
+## Subtasks
+${subtaskStr}
+
+## Instructions
+1. Read the codebase and understand the context needed for this task
+2. Report progress via harmony_update_agent_progress at key milestones:
+   - After reading codebase and forming a plan (~20%)
+   - After each major implementation step (~30-60%)
+   - After completing each subtask (also toggle via harmony_toggle_subtask)
+   - Before committing (~65%)
+   Include a brief currentTask description.
+3. Implement the changes on branch \`${branchName}\`
+4. Commit your work with clear, descriptive commit messages
+5. When finished, call harmony_end_agent_session with status="completed"
+
+You are working in a git worktree at \`${worktreePath}\` on branch \`${branchName}\`.
+Do NOT push to main. All your work stays on \`${branchName}\`.`;
+}

package/dist/queue.d.ts

@@ -0,0 +1,37 @@
+import type { Card, Column, Label } from "@harmony/shared";
+import type { AgentConfig, QueueItem, WorkMode } from "./types.js";
+/**
+ * Priority queue for cards waiting to be worked on.
+ * Sorted by: label priority boost > column position boost > enqueue time (FIFO).
+ */
+export declare class PriorityQueue {
+    private config;
+    private items;
+    constructor(config: AgentConfig);
+    /**
+     * Calculate priority score for a card.
+     */
+    scoreCard(_card: Card, column: Column, labels: Label[]): number;
+    /**
+     * Add a card to the queue. If already present, update its priority.
+     */
+    enqueue(card: Card, column: Column, labels: Label[], mode?: WorkMode): void;
+    /**
+     * Remove and return the highest-priority item.
+     */
+    dequeue(): QueueItem | null;
+    /**
+     * Remove a specific card from the queue.
+     */
+    remove(cardId: string): QueueItem | null;
+    /**
+     * Check if a card is in the queue.
+     */
+    has(cardId: string): boolean;
+    /**
+     * Get all queued card IDs.
+     */
+    cardIds(): string[];
+    get length(): number;
+    peek(): QueueItem | null;
+}

package/dist/queue.js

@@ -0,0 +1,96 @@
+import { log } from "./log.js";
+const TAG = "queue";
+/**
+ * Priority queue for cards waiting to be worked on.
+ * Sorted by: label priority boost > column position boost > enqueue time (FIFO).
+ */
+export class PriorityQueue {
+    config;
+    items = [];
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Calculate priority score for a card.
+     */
+    scoreCard(_card, column, labels) {
+        let score = 0;
+        // Label boost: highest matching label wins
+        for (const label of labels) {
+            const boost = this.config.priorityLabels[label.name.toLowerCase()] ?? 0;
+            if (boost > score)
+                score = boost;
+        }
+        // Column position boost: leftmost columns get higher priority
+        if (this.config.columnBoost) {
+            score += Math.max(0, 100 - column.position * 10);
+        }
+        return score;
+    }
+    /**
+     * Add a card to the queue. If already present, update its priority.
+     */
+    enqueue(card, column, labels, mode = "implement") {
+        const existing = this.items.findIndex((i) => i.cardId === card.id);
+        if (existing !== -1) {
+            log.debug(TAG, `Card #${card.short_id} already queued, updating priority`);
+            this.items.splice(existing, 1);
+        }
+        const priority = this.scoreCard(card, column, labels);
+        const item = {
+            cardId: card.id,
+            shortId: card.short_id,
+            title: card.title,
+            priority,
+            enqueuedAt: Date.now(),
+            mode,
+        };
+        // Insert in sorted position (highest priority first, FIFO tiebreak)
+        let insertIdx = this.items.length;
+        for (let i = 0; i < this.items.length; i++) {
+            if (priority > this.items[i].priority ||
+                (priority === this.items[i].priority &&
+                    item.enqueuedAt < this.items[i].enqueuedAt)) {
+                insertIdx = i;
+                break;
+            }
+        }
+        this.items.splice(insertIdx, 0, item);
+        log.info(TAG, `Enqueued #${card.short_id} "${card.title}" (priority=${priority}, pos=${insertIdx}, queue=${this.items.length})`);
+    }
+    /**
+     * Remove and return the highest-priority item.
+     */
+    dequeue() {
+        return this.items.shift() ?? null;
+    }
+    /**
+     * Remove a specific card from the queue.
+     */
+    remove(cardId) {
+        const idx = this.items.findIndex((i) => i.cardId === cardId);
+        if (idx === -1)
+            return null;
+        const [item] = this.items.splice(idx, 1);
+        log.info(TAG, `Removed #${item.shortId} from queue`);
+        return item;
+    }
+    /**
+     * Check if a card is in the queue.
+     */
+    has(cardId) {
+        return this.items.some((i) => i.cardId === cardId);
+    }
+    /**
+     * Get all queued card IDs.
+     */
+    cardIds() {
+        return this.items.map((i) => i.cardId);
+    }
+    get length() {
+        return this.items.length;
+    }
+    peek() {
+        return this.items[0] ?? null;
+    }
+}

package/dist/reconcile.d.ts

@@ -0,0 +1,21 @@
+import type { HarmonyApiClient } from "@gethmy/mcp/src/api-client.js";
+import type { Pool } from "./pool.js";
+/**
+ * Reconciliation heartbeat: polls the board every `intervalMs` to catch
+ * missed realtime events and sync state.
+ */
+export declare class Reconciler {
+    private client;
+    private pool;
+    private projectId;
+    private agentUserId;
+    private pickupColumns;
+    private reviewColumns;
+    private approvedLabel;
+    private intervalMs;
+    private timer;
+    constructor(client: HarmonyApiClient, pool: Pool, projectId: string, agentUserId: string, pickupColumns: string[], reviewColumns: string[], approvedLabel: string, intervalMs?: number);
+    start(): void;
+    stop(): void;
+    private tick;
+}

package/dist/reconcile.js

@@ -0,0 +1,107 @@
+import { hasApprovedLabel } from "./board-helpers.js";
+import { log } from "./log.js";
+const TAG = "reconcile";
+/**
+ * Reconciliation heartbeat: polls the board every `intervalMs` to catch
+ * missed realtime events and sync state.
+ */
+export class Reconciler {
+    client;
+    pool;
+    projectId;
+    agentUserId;
+    pickupColumns;
+    reviewColumns;
+    approvedLabel;
+    intervalMs;
+    timer = null;
+    constructor(client, pool, projectId, agentUserId, pickupColumns, reviewColumns, approvedLabel, intervalMs = 60_000) {
+        this.client = client;
+        this.pool = pool;
+        this.projectId = projectId;
+        this.agentUserId = agentUserId;
+        this.pickupColumns = pickupColumns;
+        this.reviewColumns = reviewColumns;
+        this.approvedLabel = approvedLabel;
+        this.intervalMs = intervalMs;
+    }
+    start() {
+        log.info(TAG, `Heartbeat every ${this.intervalMs / 1000}s`);
+        // Run immediately, then on interval
+        this.tick();
+        this.timer = setInterval(() => this.tick(), this.intervalMs);
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        log.info(TAG, "Heartbeat stopped");
+    }
+    async tick() {
+        try {
+            const board = await this.client.getBoard(this.projectId);
+            const cards = (board.cards ?? []);
+            const columns = board.columns;
+            const _labels = (board.labels ?? []);
+            // Build a lookup of columns by ID
+            const columnMap = new Map();
+            for (const col of columns) {
+                columnMap.set(col.id, col);
+            }
+            // Build column ID sets for both modes
+            const pickupColumnIds = new Set(columns
+                .filter((c) => this.pickupColumns.some((name) => name.toLowerCase() === c.name.toLowerCase()))
+                .map((c) => c.id));
+            const reviewColumnIds = new Set(columns
+                .filter((c) => this.reviewColumns.some((name) => name.toLowerCase() === c.name.toLowerCase()))
+                .map((c) => c.id));
+            // Find cards assigned to our agent in either pickup or review columns
+            const assignedCards = cards.filter((c) => c.assignee_id === this.agentUserId &&
+                !c.archived_at &&
+                (pickupColumnIds.has(c.column_id) ||
+                    reviewColumnIds.has(c.column_id)));
+            const knownCardIds = this.pool.knownCardIds();
+            // All cards still assigned to the agent (any column) — used to detect
+            // genuine unassigns without false-positiving on cards the worker moved
+            // to "In Progress" or other non-pickup columns.
+            const allAgentCardIds = new Set(cards
+                .filter((c) => c.assignee_id === this.agentUserId && !c.archived_at)
+                .map((c) => c.id));
+            // Cards assigned but NOT in queue/active → enqueue (missed event)
+            for (const card of assignedCards) {
+                if (!knownCardIds.has(card.id)) {
+                    const column = columnMap.get(card.column_id);
+                    if (!column)
+                        continue;
+                    const cardLabels = card.labels ?? [];
+                    const subtasks = card.subtasks ?? [];
+                    // Determine mode based on which column set the card is in
+                    const mode = reviewColumnIds.has(card.column_id)
+                        ? "review"
+                        : "implement";
+                    // Skip already-approved cards in review mode
+                    if (mode === "review" &&
+                        this.approvedLabel &&
+                        hasApprovedLabel(cardLabels, this.approvedLabel)) {
+                        log.debug(TAG, `Skipping #${card.short_id} — already has "${this.approvedLabel}" label`);
+                        continue;
+                    }
+                    log.info(TAG, `Missed assignment: #${card.short_id} "${card.title}" (${mode}) — enqueueing`);
+                    this.pool.enqueue(card, column, cardLabels, subtasks, mode);
+                }
+            }
+            // Cards in queue/active but no longer assigned to agent → cancel/remove
+            for (const knownId of knownCardIds) {
+                if (!allAgentCardIds.has(knownId)) {
+                    log.info(TAG, `Missed unassign: ${knownId} — removing`);
+                    await this.pool.removeCard(knownId);
+                }
+            }
+            log.debug(TAG, `Reconciled: ${assignedCards.length} assigned, ${knownCardIds.size} known`);
+        }
+        catch (err) {
+            log.error(TAG, `Heartbeat failed: ${err instanceof Error ? err.message : err}`);
+        }
+    }
+}

package/dist/review-completion.d.ts

@@ -0,0 +1,31 @@
+import type { HarmonyApiClient } from "@gethmy/mcp/src/api-client.js";
+import type { Card } from "@harmony/shared";
+import type { AgentConfig } from "./types.js";
+export interface ReviewFinding {
+    severity: "critical" | "major" | "minor";
+    title: string;
+    description: string;
+    category?: string;
+    location?: string;
+}
+export interface ScopeCheck {
+    status: "clean" | "drift" | "missing";
+    notes?: string;
+}
+export interface ReviewResult {
+    verdict: "approved" | "rejected";
+    summary: string;
+    scopeCheck?: ScopeCheck;
+    findings: ReviewFinding[];
+}
+/**
+ * Parse Claude's review output into a structured ReviewResult.
+ * Looks for a JSON block in the output.
+ */
+export declare function parseReviewOutput(stdout: string): ReviewResult;
+/**
+ * Post-review completion pipeline.
+ * Handles approved/rejected verdicts, creates subtasks for findings,
+ * and moves the card to the appropriate column.
+ */
+export declare function runReviewCompletion(client: HarmonyApiClient, card: Card, result: ReviewResult, config: AgentConfig, worktreePath: string, branchName: string): Promise<void>;