@gethmy/agent 1.0.1 → 1.0.3

package/README.md

@@ -4,10 +4,11 @@ Push-based agent daemon for [Harmony](https://gethmy.com). Watches board assignm
 
 ## Prerequisites
 
-- [Node.js](https://nodejs.org) >= 18 or [Bun](https://bun.sh) >= 1.0.0
-- [Claude CLI](https://docs.anthropic.com/en/docs/claude-code)
+- [Node.js](https://nodejs.org) >= 20 or [Bun](https://bun.sh) >= 1.0
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI installed
 - Git
 - A [Harmony](https://gethmy.com) account with an API key
+- [@gethmy/mcp](https://www.npmjs.com/package/@gethmy/mcp) configured (`npx @gethmy/mcp setup`)
 
 ## Installation
 

package/dist/board-helpers.d.ts

@@ -1,9 +1,17 @@
 import type { HarmonyApiClient } from "@gethmy/mcp/src/api-client.js";
 import type { Card, Label } from "@harmony/shared";
 /**
- * Check if a card already has the approved label (case-insensitive).
+ * Build a label lookup map from board-level label definitions.
  */
-export declare function hasApprovedLabel(cardLabels: Label[], approvedLabel: string): boolean;
+export declare function buildLabelMap(boardLabels: Label[]): Map<string, Label>;
+/**
+ * Resolve a card's `labelIds` to full Label objects using a label map.
+ */
+export declare function resolveCardLabels(card: Card, labelMap: Map<string, Label>): Label[];
+/**
+ * Check if a card has a label by name (case-insensitive).
+ */
+export declare function hasLabel(cardLabels: Label[], labelName: string): boolean;
 /**
  * Move a card to a column by name. Fetches the board to resolve column ID.
  */

package/dist/board-helpers.js

@@ -1,10 +1,29 @@
 import { log } from "./log.js";
 const TAG = "board";
 /**
- * Check if a card already has the approved label (case-insensitive).
+ * Build a label lookup map from board-level label definitions.
  */
-export function hasApprovedLabel(cardLabels, approvedLabel) {
-    return cardLabels.some((l) => l.name.toLowerCase() === approvedLabel.toLowerCase());
+export function buildLabelMap(boardLabels) {
+    const map = new Map();
+    for (const label of boardLabels) {
+        map.set(label.id, label);
+    }
+    return map;
+}
+/**
+ * Resolve a card's `labelIds` to full Label objects using a label map.
+ */
+export function resolveCardLabels(card, labelMap) {
+    const ids = card.labelIds ?? [];
+    return ids
+        .map((id) => labelMap.get(id))
+        .filter((l) => l !== undefined);
+}
+/**
+ * Check if a card has a label by name (case-insensitive).
+ */
+export function hasLabel(cardLabels, labelName) {
+    return cardLabels.some((l) => l.name.toLowerCase() === labelName.toLowerCase());
 }
 /**
  * Move a card to a column by name. Fetches the board to resolve column ID.

package/dist/completion.d.ts

@@ -1,7 +1,14 @@
 import type { HarmonyApiClient } from "@gethmy/mcp/src/api-client.js";
 import type { Card } from "@harmony/shared";
+import type { CostUpdate } from "./stream-parser.js";
 import { type AgentConfig } from "./types.js";
+export interface SessionStats {
+    filesEdited: number;
+    filesRead: number;
+    toolCalls: number;
+    cost: CostUpdate | null;
+}
 /**
  * Post-work pipeline: push branch, create PR, move card, post summary.
  */
-export declare function runCompletion(client: HarmonyApiClient, card: Card, branchName: string, worktreePath: string, config: AgentConfig, workerId?: number): Promise<void>;
+export declare function runCompletion(client: HarmonyApiClient, card: Card, branchName: string, worktreePath: string, config: AgentConfig, workerId?: number, sessionStats?: SessionStats): Promise<void>;

package/dist/completion.js

@@ -6,11 +6,10 @@ import { AGENT_NAME, agentIdentifier } from "./types.js";
 import { attemptAutoFix, reportFindings, runVerification, } from "./verification.js";
 import { cleanupWorktree } from "./worktree.js";
 const TAG = "completion";
-// ============ COMPLETION PIPELINE ============
 /**
  * Post-work pipeline: push branch, create PR, move card, post summary.
  */
-export async function runCompletion(client, card, branchName, worktreePath, config, workerId = 0) {
+export async function runCompletion(client, card, branchName, worktreePath, config, workerId = 0, sessionStats) {
     // Check if there are any commits on the branch
     const hasCommits = checkHasCommits(worktreePath, config.worktree.baseBranch);
     if (!hasCommits) {
@@ -76,7 +75,7 @@ export async function runCompletion(client, card, branchName, worktreePath, conf
     }
     // 5. Post summary — always includes branch, optionally PR link
     if (config.completion.postSummary) {
-        await postSummary(client, card, branchName, worktreePath, prUrl, config.worktree.baseBranch);
+        await postSummary(client, card, branchName, worktreePath, prUrl, config.worktree.baseBranch, sessionStats);
     }
     // 6. End agent session
     await client.endAgentSession(card.id, {
@@ -96,7 +95,7 @@ function checkHasCommits(worktreePath, baseBranch) {
         return false;
     }
 }
-async function postSummary(client, card, branchName, worktreePath, prUrl, baseBranch) {
+async function postSummary(client, card, branchName, worktreePath, prUrl, baseBranch, sessionStats) {
     // Build commit summary
     let commitLog = "";
     try {
@@ -112,6 +111,17 @@ async function postSummary(client, card, branchName, worktreePath, prUrl, baseBr
         parts.push(`PR: ${prUrl}`);
     }
     parts.push(`Branch: \`${branchName}\``);
+    if (sessionStats) {
+        const statParts = [];
+        statParts.push(`${sessionStats.toolCalls} tool calls`);
+        statParts.push(`${sessionStats.filesEdited} files edited`);
+        statParts.push(`${sessionStats.filesRead} files read`);
+        if (sessionStats.cost) {
+            statParts.push(`$${sessionStats.cost.totalCostUsd.toFixed(2)} cost`);
+            statParts.push(`${sessionStats.cost.numTurns} turns`);
+        }
+        parts.push(`Stats: ${statParts.join(" · ")}`);
+    }
     if (commitLog) {
         parts.push(`\n\`\`\`\n${commitLog}\n\`\`\``);
     }

package/dist/index.js

@@ -1,5 +1,5 @@
 import { execFileSync } from "node:child_process";
-import { hasApprovedLabel } from "./board-helpers.js";
+import { buildLabelMap, hasLabel, resolveCardLabels } from "./board-helpers.js";
 import { createApiClient, fetchRealtimeCredentials, loadDaemonConfig, } from "./config.js";
 import { detectGitProvider, validateGitProviderCli } from "./git-pr.js";
 import { log } from "./log.js";
@@ -101,9 +101,11 @@ async function main() {
     if (config.agent.review.enabled && config.agent.review.mergeMonitor) {
         mergeMonitor = new MergeMonitor(client, config.projectId, config.agent);
     }
-    // Create watcher (broadcast events from harmony-api)
+    // Create watcher (broadcast events from harmony-api + agent commands from UI)
     const watcher = new Watcher(realtimeCreds, config.projectId, async (event) => {
         await handleBroadcast(event, client, pool, config, agentUserId);
+    }, async (command) => {
+        await pool.handleAgentCommand(command.cardId, command.command);
     });
     // Wire up shutdown
     let shuttingDown = false;
@@ -160,7 +162,7 @@ async function handleBroadcast(event, client, pool, config, agentUserId) {
  */
 async function tryEnqueueCard(cardId, client, pool, config) {
     const { card } = (await client.getCard(cardId));
-    const board = await client.getBoard(config.projectId);
+    const board = await client.getBoard(config.projectId, { summary: true });
     const columns = board.columns;
     const column = columns.find((c) => c.id === card.column_id);
     if (!column) {
@@ -177,12 +179,14 @@ async function tryEnqueueCard(cardId, client, pool, config) {
         return;
     }
     const mode = isReviewColumn ? "review" : "implement";
-    const cardLabels = card.labels ?? [];
+    // Resolve card labels from labelIds using board-level label definitions
+    const labelMap = buildLabelMap((board.labels ?? []));
+    const cardLabels = resolveCardLabels(card, labelMap);
     const subtasks = card.subtasks ?? [];
     // Skip already-approved cards in review mode
     if (mode === "review" &&
         config.agent.review.approvedLabel &&
-        hasApprovedLabel(cardLabels, config.agent.review.approvedLabel)) {
+        hasLabel(cardLabels, config.agent.review.approvedLabel)) {
         log.debug(TAG, `Card #${card.short_id} already has "${config.agent.review.approvedLabel}" — skipping review`);
         return;
     }

package/dist/merge-monitor.js

@@ -1,6 +1,6 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
-import { addLabelByName, hasApprovedLabel, moveCardToColumn, } from "./board-helpers.js";
+import { addLabelByName, buildLabelMap, hasLabel, moveCardToColumn, resolveCardLabels, } from "./board-helpers.js";
 import { checkPrMergeStatus, detectGitProvider, extractPrUrl, } from "./git-pr.js";
 import { log } from "./log.js";
 import { extractBranchFromDescription } from "./review-worktree.js";
@@ -54,27 +54,39 @@ export class MergeMonitor {
     }
     async tick() {
         try {
-            const board = await this.client.getBoard(this.projectId);
+            const board = await this.client.getBoard(this.projectId, {
+                labelName: this.config.review.approvedLabel,
+            });
             const cards = (board.cards ?? []);
             const columns = (board.columns ?? []);
+            // Build label lookup (id → Label) to resolve card.labelIds
+            const labelMap = buildLabelMap((board.labels ?? []));
             // Find review column IDs
             const reviewColumnIds = new Set(columns
                 .filter((c) => this.config.review.pickupColumns.some((name) => name.toLowerCase() === c.name.toLowerCase()))
                 .map((c) => c.id));
-            // Filter cards in review columns that have the "Ready to Merge" label
+            // Cards are already pre-filtered by the approved label server-side via
+            // the `labelName` param. The column + label checks below are kept as
+            // defense-in-depth against API changes or stale cache.
             const approvedLabel = this.config.review.approvedLabel;
-            const candidates = cards.filter((c) => !c.archived_at &&
-                reviewColumnIds.has(c.column_id) &&
-                hasApprovedLabel((c.labels ?? []), approvedLabel));
-            if (candidates.length === 0) {
+            const candidatesWithLabels = [];
+            for (const c of cards) {
+                if (c.archived_at || !reviewColumnIds.has(c.column_id))
+                    continue;
+                const labels = resolveCardLabels(c, labelMap);
+                if (hasLabel(labels, approvedLabel)) {
+                    candidatesWithLabels.push({ card: c, labels });
+                }
+            }
+            if (candidatesWithLabels.length === 0) {
                 log.debug(TAG, "No Ready to Merge cards found");
                 return;
             }
             // Process max 5 per tick to respect rate limits
-            const batch = candidates.slice(0, 5);
+            const batch = candidatesWithLabels.slice(0, 5);
             log.debug(TAG, `Checking ${batch.length} Ready to Merge card(s)`);
             // Check PR states concurrently (async, non-blocking)
-            const results = await Promise.allSettled(batch.map(async (card) => {
+            const results = await Promise.allSettled(batch.map(async ({ card, labels }) => {
                 const prUrl = extractPrUrl(card.description ?? null);
                 if (!prUrl) {
                     log.debug(TAG, `#${card.short_id} has no PR URL — skipping`);
@@ -83,7 +95,7 @@ export class MergeMonitor {
                 const state = await checkPrMergeStatus(prUrl, this.cwd, this.provider);
                 if (state === "merged") {
                     log.info(TAG, `#${card.short_id} PR merged — completing`);
-                    await this.completeMergedCard(card);
+                    await this.completeMergedCard(card, labels);
                 }
                 else {
                     log.debug(TAG, `#${card.short_id} PR state: ${state}`);
@@ -99,7 +111,7 @@ export class MergeMonitor {
             log.error(TAG, `Tick failed: ${err instanceof Error ? err.message : err}`);
         }
     }
-    async completeMergedCard(card) {
+    async completeMergedCard(card, resolvedLabels) {
         // 1. Move to Done — bail if this fails since subsequent steps assume card is in Done
         try {
             await moveCardToColumn(this.client, card, this.config.review.moveToColumn);
@@ -112,8 +124,7 @@ export class MergeMonitor {
         await addLabelByName(this.client, card, this.config.review.mergedLabel, this.config.review.mergedLabelColor);
         // 3. Remove "Ready to Merge" label
         const approvedLabelName = this.config.review.approvedLabel.toLowerCase();
-        const cardLabels = (card.labels ?? []);
-        const approvedLabelObj = cardLabels.find((l) => l.name.toLowerCase() === approvedLabelName);
+        const approvedLabelObj = resolvedLabels.find((l) => l.name.toLowerCase() === approvedLabelName);
         if (approvedLabelObj) {
             try {
                 await this.client.removeLabelFromCard(card.id, approvedLabelObj.id);
@@ -123,19 +134,20 @@ export class MergeMonitor {
                 log.warn(TAG, `Failed to remove label: ${err instanceof Error ? err.message : err}`);
             }
         }
-        // 4. Append merge timestamp to description (idempotent)
+        // 4. Mark done + append merge timestamp to description (idempotent)
         const existing = card.description || "";
-        if (!existing.includes("Merged at")) {
-            try {
+        const alreadyStamped = existing.includes("Merged at");
+        try {
+            const update = { done: true };
+            if (!alreadyStamped) {
                 const timestamp = new Date().toISOString();
                 const separator = existing ? "\n" : "";
-                await this.client.updateCard(card.id, {
-                    description: `${existing}${separator}Merged at ${timestamp}`,
-                });
-            }
-            catch (err) {
-                log.warn(TAG, `Failed to update description: ${err instanceof Error ? err.message : err}`);
+                update.description = `${existing}${separator}Merged at ${timestamp}`;
             }
+            await this.client.updateCard(card.id, update);
+        }
+        catch (err) {
+            log.warn(TAG, `Failed to update card: ${err instanceof Error ? err.message : err}`);
         }
         // 5. Best-effort: clean up local branch (uses shared extraction with validation)
         const branchName = extractBranchFromDescription(card.description);

package/dist/pool.d.ts

@@ -27,6 +27,10 @@ export declare class Pool {
      * Get all card IDs that are either queued or active.
      */
     knownCardIds(): Set<string>;
+    /**
+     * Handle an agent command (pause/resume/stop) for a specific card.
+     */
+    handleAgentCommand(cardId: string, command: "pause" | "resume" | "stop"): Promise<void>;
     /**
      * Gracefully shutdown all workers.
      */

package/dist/pool.js

@@ -99,6 +99,29 @@ export class Pool {
         }
         return ids;
     }
+    /**
+     * Handle an agent command (pause/resume/stop) for a specific card.
+     */
+    async handleAgentCommand(cardId, command) {
+        const worker = this.implWorkers.find((w) => w.cardId === cardId && w.isActive) ??
+            this.reviewWorkers.find((w) => w.cardId === cardId && w.isActive);
+        if (!worker) {
+            log.debug(TAG, `No active worker for card ${cardId}, ignoring ${command}`);
+            return;
+        }
+        log.info(TAG, `Agent command: ${command} → worker ${worker.id} (card ${cardId})`);
+        switch (command) {
+            case "pause":
+                await worker.pause();
+                break;
+            case "resume":
+                await worker.resume();
+                break;
+            case "stop":
+                await worker.cancel();
+                break;
+        }
+    }
     /**
      * Gracefully shutdown all workers.
      */

package/dist/progress-tracker.d.ts

@@ -1,5 +1,5 @@
 import type { HarmonyApiClient } from "@gethmy/mcp/src/api-client.js";
-import type { StreamParser } from "./stream-parser.js";
+import type { CostUpdate, StreamParser } from "./stream-parser.js";
 export declare class ProgressTracker {
     private client;
     private cardId;
@@ -10,11 +10,17 @@ export declare class ProgressTracker {
     private hasEdited;
     private lastUpdateAt;
     private pendingUpdate;
+    private pendingTask;
     private heartbeatTimer;
     private stopped;
+    private lastAction;
     private subtaskTotal;
     private subtaskCompleted;
     private subtaskMode;
+    private filesEdited;
+    private filesRead;
+    private lastCost;
+    private recentActions;
     constructor(client: HarmonyApiClient, cardId: string, workerId: number, subtasks: {
         completed: boolean;
     }[]);
@@ -26,14 +32,33 @@ export declare class ProgressTracker {
      * Stop all timers and flush any pending update.
      */
     stop(): void;
+    /** Get a summary of the session stats. */
+    get stats(): {
+        filesEdited: number;
+        filesRead: number;
+        toolCalls: number;
+        cost: CostUpdate | null;
+    };
     private onToolStart;
     private onToolEnd;
+    private onText;
     private transitionTo;
     private incrementProgress;
     private currentTaskLabel;
+    /**
+     * Build a human-readable description of what a tool call is doing.
+     */
+    private describeToolAction;
+    /**
+     * Strip absolute paths to show only meaningful segments from src/ or packages/.
+     */
+    private shortPath;
     private scheduleUpdate;
+    private pushRecentAction;
     private sendUpdate;
     private startHeartbeat;
-    private phaseOrder;
-    private extractBashCommand;
+    /**
+     * Safely extract a string property from an unknown tool input.
+     */
+    private extractString;
 }