@gethmy/agent 1.0.9 → 1.1.1

package/dist/state-store.js

@@ -0,0 +1,216 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { log } from "./log.js";
+const TAG = "state-store";
+const SCHEMA_VERSION = 1;
+function emptyState() {
+    return {
+        version: SCHEMA_VERSION,
+        daemonId: null,
+        daemonPid: null,
+        daemonStartedAt: null,
+        runs: [],
+        cards: [],
+        daily: [],
+    };
+}
+function todayUtc() {
+    return new Date().toISOString().slice(0, 10);
+}
+export function newRunId() {
+    const ts = Date.now().toString(36);
+    const rand = Math.random().toString(36).slice(2, 10);
+    return `r_${ts}_${rand}`;
+}
+export function defaultStatePath() {
+    return join(homedir(), ".harmony-mcp", "agent-state.json");
+}
+/**
+ * Durable run-and-card state for the agent daemon. One writer (this daemon),
+ * so in-process serialization via a promise chain is sufficient — no file locks.
+ * Persists to JSON via write-to-tmp + rename, which is atomic on POSIX.
+ */
+export class StateStore {
+    path;
+    state;
+    writeQueue = Promise.resolve();
+    constructor(path) {
+        this.path = path;
+        this.state = this.load();
+    }
+    static open(path) {
+        const resolved = path ?? defaultStatePath();
+        const dir = dirname(resolved);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        return new StateStore(resolved);
+    }
+    load() {
+        if (!existsSync(this.path))
+            return emptyState();
+        try {
+            const raw = readFileSync(this.path, "utf-8");
+            const parsed = JSON.parse(raw);
+            if (parsed?.version !== SCHEMA_VERSION) {
+                log.warn(TAG, `state file has version ${parsed?.version}, expected ${SCHEMA_VERSION} — starting fresh`);
+                return emptyState();
+            }
+            return {
+                version: SCHEMA_VERSION,
+                daemonId: parsed.daemonId ?? null,
+                daemonPid: parsed.daemonPid ?? null,
+                daemonStartedAt: parsed.daemonStartedAt ?? null,
+                runs: parsed.runs ?? [],
+                cards: parsed.cards ?? [],
+                daily: parsed.daily ?? [],
+            };
+        }
+        catch (err) {
+            log.error(TAG, `failed to read state file: ${err instanceof Error ? err.message : err}`);
+            return emptyState();
+        }
+    }
+    persist() {
+        const fire = async () => {
+            const tmp = `${this.path}.tmp`;
+            const data = JSON.stringify(this.state, null, 2);
+            writeFileSync(tmp, data, "utf-8");
+            renameSync(tmp, this.path);
+        };
+        this.writeQueue = this.writeQueue.then(fire, fire);
+        return this.writeQueue;
+    }
+    /** Await any pending writes. Useful for tests and shutdown. */
+    flush() {
+        return this.writeQueue;
+    }
+    // ---------- Daemon metadata ----------
+    setDaemon(daemonId, pid) {
+        this.state.daemonId = daemonId;
+        this.state.daemonPid = pid;
+        this.state.daemonStartedAt = Date.now();
+        return this.persist();
+    }
+    getDaemon() {
+        return {
+            daemonId: this.state.daemonId,
+            daemonPid: this.state.daemonPid,
+            daemonStartedAt: this.state.daemonStartedAt,
+        };
+    }
+    // ---------- Runs ----------
+    insertRun(run) {
+        this.state.runs.push(run);
+        return this.persist();
+    }
+    updateRun(runId, patch) {
+        const idx = this.state.runs.findIndex((r) => r.runId === runId);
+        if (idx === -1)
+            return Promise.resolve();
+        this.state.runs[idx] = { ...this.state.runs[idx], ...patch };
+        return this.persist();
+    }
+    heartbeat(runId) {
+        return this.updateRun(runId, { lastHeartbeatAt: Date.now() });
+    }
+    endRun(runId, status, errorMessage) {
+        const patch = {
+            status,
+            endedAt: Date.now(),
+        };
+        if (errorMessage !== undefined)
+            patch.errorMessage = errorMessage;
+        return this.updateRun(runId, patch);
+    }
+    getRun(runId) {
+        return this.state.runs.find((r) => r.runId === runId) ?? null;
+    }
+    getActiveRuns() {
+        return this.state.runs.filter((r) => r.endedAt === null);
+    }
+    getRunsForCard(cardId) {
+        return this.state.runs.filter((r) => r.cardId === cardId);
+    }
+    /** Trim completed runs older than `beforeTs` to keep the file small. */
+    purgeOldRuns(beforeTs) {
+        this.state.runs = this.state.runs.filter((r) => r.endedAt === null || r.endedAt >= beforeTs);
+        return this.persist();
+    }
+    // ---------- Cards ----------
+    ensureCard(cardId) {
+        let rec = this.state.cards.find((c) => c.cardId === cardId);
+        if (!rec) {
+            rec = {
+                cardId,
+                attempts: 0,
+                totalCostCents: 0,
+                dlq: false,
+                lastAttemptAt: null,
+                lastOutcome: null,
+            };
+            this.state.cards.push(rec);
+        }
+        return rec;
+    }
+    getCard(cardId) {
+        return this.state.cards.find((c) => c.cardId === cardId) ?? null;
+    }
+    async incrementAttempt(cardId) {
+        const rec = this.ensureCard(cardId);
+        rec.attempts += 1;
+        rec.lastAttemptAt = Date.now();
+        await this.persist();
+        return rec.attempts;
+    }
+    async recordOutcome(cardId, outcome) {
+        const rec = this.ensureCard(cardId);
+        rec.lastOutcome = outcome;
+        if (outcome === "success")
+            rec.attempts = 0;
+        await this.persist();
+    }
+    async addCost(cardId, cents) {
+        if (cents <= 0)
+            return;
+        const rec = this.ensureCard(cardId);
+        rec.totalCostCents += cents;
+        const today = todayUtc();
+        let daily = this.state.daily.find((d) => d.date === today);
+        if (!daily) {
+            daily = { date: today, costCents: 0 };
+            this.state.daily.push(daily);
+        }
+        daily.costCents += cents;
+        const cutoff = new Date(Date.now() - 30 * 86_400_000)
+            .toISOString()
+            .slice(0, 10);
+        this.state.daily = this.state.daily.filter((d) => d.date >= cutoff);
+        await this.persist();
+    }
+    getDailyCostCents(date) {
+        const key = date ?? todayUtc();
+        return this.state.daily.find((d) => d.date === key)?.costCents ?? 0;
+    }
+    // ---------- DLQ ----------
+    async markDlq(cardId, reason) {
+        const rec = this.ensureCard(cardId);
+        rec.dlq = true;
+        rec.dlqReason = reason;
+        await this.persist();
+    }
+    async clearDlq(cardId) {
+        const rec = this.getCard(cardId);
+        if (!rec)
+            return;
+        rec.dlq = false;
+        delete rec.dlqReason;
+        await this.persist();
+    }
+    isDlq(cardId) {
+        return this.getCard(cardId)?.dlq === true;
+    }
+    listDlq() {
+        return this.state.cards.filter((c) => c.dlq);
+    }
+}

package/dist/transitions.d.ts

@@ -0,0 +1,57 @@
+import type { HarmonyApiClient } from "@gethmy/mcp/src/api-client.js";
+import type { Card } from "@harmony/shared";
+import type { StateStore } from "./state-store.js";
+export type TransitionStep = "move" | "addLabel" | "removeLabel" | "updateCard" | "endSession";
+export declare class TransitionError extends Error {
+    readonly step: TransitionStep;
+    readonly attempts: number;
+    readonly detail: string;
+    constructor(step: TransitionStep, attempts: number, detail: string, options?: {
+        cause?: unknown;
+    });
+}
+export interface EndSessionArgs {
+    status: "completed" | "paused";
+    progressPercent?: number;
+    costCents?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+}
+export interface TransitionPlan {
+    /** Target column name. No-op if the card is already there. */
+    move?: {
+        columnName: string;
+    };
+    /** Labels to add (idempotent — existing labels skipped). */
+    addLabels?: Array<{
+        name: string;
+        color?: string;
+    }>;
+    /** Labels to remove (idempotent — missing labels skipped). */
+    removeLabels?: string[];
+    /** Arbitrary card field updates. */
+    updateCard?: {
+        description?: string;
+        title?: string;
+    };
+    /** End the active agent session. */
+    endSession?: EndSessionArgs;
+}
+export interface TransitionOptions {
+    retries?: number;
+    backoffMs?: number;
+    store?: StateStore;
+    runId?: string;
+    /** If true, a missing column throws instead of being a no-op. */
+    strictColumn?: boolean;
+}
+/**
+ * Execute a board transition as an ordered, retriable sequence of steps.
+ *
+ * Replaces the scattered `try { ... } catch { /* best-effort * / }` pattern
+ * so every partial failure surfaces with structured context. Operations
+ * are individually idempotent (move-to-same-column is a no-op, add/remove
+ * label checks existing state) so re-running a partially-succeeded
+ * transition is safe.
+ */
+export declare function runTransition(client: HarmonyApiClient, card: Card, plan: TransitionPlan, opts?: TransitionOptions): Promise<void>;

package/dist/transitions.js

@@ -0,0 +1,131 @@
+import { log } from "./log.js";
+const TAG = "transition";
+export class TransitionError extends Error {
+    step;
+    attempts;
+    detail;
+    constructor(step, attempts, detail, options) {
+        super(`${step} failed after ${attempts} attempt(s): ${detail}`, options);
+        this.step = step;
+        this.attempts = attempts;
+        this.detail = detail;
+        this.name = "TransitionError";
+    }
+}
+/**
+ * Retry a flaky step with exponential backoff. Only the last error is
+ * thrown — intermediate errors are logged as warnings so operators can
+ * see that retries happened without losing the final cause.
+ */
+async function withRetry(step, cardShortId, op, attempts, backoffMs) {
+    let lastErr;
+    for (let i = 0; i < attempts; i++) {
+        try {
+            return await op();
+        }
+        catch (err) {
+            lastErr = err;
+            const msg = err instanceof Error ? err.message : String(err);
+            if (i < attempts - 1) {
+                const wait = backoffMs * 2 ** i;
+                log.warn(TAG, `${step} failed for #${cardShortId} (attempt ${i + 1}/${attempts}): ${msg} — retrying in ${wait}ms`);
+                await new Promise((r) => setTimeout(r, wait));
+            }
+        }
+    }
+    const msg = lastErr instanceof Error ? lastErr.message : String(lastErr);
+    throw new TransitionError(step, attempts, msg, { cause: lastErr });
+}
+/**
+ * Execute a board transition as an ordered, retriable sequence of steps.
+ *
+ * Replaces the scattered `try { ... } catch { /* best-effort * / }` pattern
+ * so every partial failure surfaces with structured context. Operations
+ * are individually idempotent (move-to-same-column is a no-op, add/remove
+ * label checks existing state) so re-running a partially-succeeded
+ * transition is safe.
+ */
+export async function runTransition(client, card, plan, opts = {}) {
+    const attempts = opts.retries ?? 3;
+    const backoffMs = opts.backoffMs ?? 500;
+    const shortId = card.short_id;
+    // Fetch the board once so we can resolve columns and labels together.
+    // Mutations to card state (move, label add/remove) all invalidate the
+    // same board-level data anyway, so one read is enough.
+    const board = (await withRetry("move", shortId, () => client.getBoard(card.project_id), attempts, backoffMs));
+    const columns = board.columns;
+    const labels = board.labels ?? [];
+    // --- 1. MOVE ---
+    if (plan.move) {
+        const target = columns.find((c) => c.name.toLowerCase() === plan.move.columnName.toLowerCase());
+        if (!target) {
+            const msg = `column "${plan.move.columnName}" not found`;
+            if (opts.strictColumn) {
+                throw new TransitionError("move", 1, msg);
+            }
+            log.warn(TAG, `#${shortId}: ${msg} — skipping move`);
+        }
+        else if (card.column_id !== target.id) {
+            await withRetry("move", shortId, () => client.moveCard(card.id, target.id), attempts, backoffMs);
+            log.info(TAG, `#${shortId} → "${target.name}"`);
+            card.column_id = target.id;
+        }
+    }
+    // --- 2. ADD LABELS ---
+    if (plan.addLabels?.length) {
+        const existing = new Set(card.labelIds ?? []);
+        for (const { name, color } of plan.addLabels) {
+            const match = labels.find((l) => l.name.toLowerCase() === name.toLowerCase());
+            const labelId = match?.id ??
+                (await ensureLabel(client, card.project_id, name, color, attempts, backoffMs));
+            if (!labelId || existing.has(labelId))
+                continue;
+            await withRetry("addLabel", shortId, () => client.addLabelToCard(card.id, labelId), attempts, backoffMs);
+            existing.add(labelId);
+            log.info(TAG, `#${shortId} +label "${name}"`);
+        }
+        card.labelIds = Array.from(existing);
+    }
+    // --- 3. REMOVE LABELS ---
+    if (plan.removeLabels?.length) {
+        const existing = new Set(card.labelIds ?? []);
+        for (const name of plan.removeLabels) {
+            const match = labels.find((l) => l.name.toLowerCase() === name.toLowerCase());
+            if (!match || !existing.has(match.id))
+                continue;
+            await withRetry("removeLabel", shortId, () => client.removeLabelFromCard(card.id, match.id), attempts, backoffMs);
+            existing.delete(match.id);
+            log.info(TAG, `#${shortId} -label "${name}"`);
+        }
+        card.labelIds = Array.from(existing);
+    }
+    // --- 4. UPDATE CARD ---
+    if (plan.updateCard) {
+        await withRetry("updateCard", shortId, () => client.updateCard(card.id, plan.updateCard), attempts, backoffMs);
+        log.info(TAG, `#${shortId} updated`);
+    }
+    // --- 5. END SESSION ---
+    if (plan.endSession) {
+        await withRetry("endSession", shortId, () => client.endAgentSession(card.id, plan.endSession), attempts, backoffMs);
+        log.info(TAG, `#${shortId} session ended (${plan.endSession.status})`);
+    }
+    // --- Audit trail ---
+    if (opts.store && opts.runId) {
+        try {
+            await opts.store.heartbeat(opts.runId);
+        }
+        catch {
+            // non-fatal
+        }
+    }
+}
+async function ensureLabel(client, projectId, name, color, attempts, backoffMs) {
+    try {
+        const result = await withRetry("addLabel", 0, () => client.createLabel(projectId, { name, color: color ?? "#8b5cf6" }), attempts, backoffMs);
+        return result?.label?.id ?? null;
+    }
+    catch (err) {
+        log.warn(TAG, `ensureLabel "${name}" failed: ${err instanceof Error ? err.message : err}`);
+        return null;
+    }
+}

package/dist/types.d.ts

@@ -48,6 +48,29 @@ export interface AgentConfig {
         mergedLabel: string;
         mergedLabelColor: string;
     };
+    budget: {
+        /** Max implement attempts per card before DLQ (reset on success). */
+        maxAttemptsPerCard: number;
+        /** Max cumulative spend per card, in cents, before DLQ. */
+        maxCentsPerCard: number;
+        /** Daily spend cap, in cents (UTC day). Exceeded → pause pickups. */
+        dailyBudgetCents: number;
+        /** Label applied to DLQ'd cards. */
+        dlqLabel: string;
+        dlqLabelColor: string;
+    };
+    http: {
+        /** Local HTTP status/control server. Bound to 127.0.0.1 by default. */
+        enabled: boolean;
+        port: number;
+        bindAddr: string;
+    };
+    timing: {
+        heartbeatMs: number;
+        staleHeartbeatMs: number;
+        reconcileIntervalMs: number;
+        worktreeGcIntervalMs: number;
+    };
 }
 export declare const DEFAULT_AGENT_CONFIG: AgentConfig;
 export declare const NEED_REVIEW_LABEL = "Need Review";

package/dist/types.js

@@ -28,7 +28,7 @@ export const DEFAULT_AGENT_CONFIG = {
         deepReview: false,
         devServerBasePort: 4200,
         timeout: 120_000,
-        failColumn: "Needs Fix",
+        failColumn: "To Do",
     },
     review: {
         enabled: true,
@@ -46,6 +46,24 @@ export const DEFAULT_AGENT_CONFIG = {
         mergedLabel: "Merged",
         mergedLabelColor: "#6366f1",
     },
+    budget: {
+        maxAttemptsPerCard: 3,
+        maxCentsPerCard: 500, // $5.00
+        dailyBudgetCents: 5000, // $50.00
+        dlqLabel: "dlq",
+        dlqLabelColor: "#dc2626",
+    },
+    http: {
+        enabled: true,
+        port: 47821,
+        bindAddr: "127.0.0.1",
+    },
+    timing: {
+        heartbeatMs: 30_000,
+        staleHeartbeatMs: 120_000,
+        reconcileIntervalMs: 60_000,
+        worktreeGcIntervalMs: 5 * 60_000,
+    },
 };
 // ============ LABELS ============
 export const NEED_REVIEW_LABEL = "Need Review";

package/dist/verification.d.ts

@@ -13,4 +13,21 @@ 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 class DevServerReadinessError extends Error {
+    constructor(message: string);
+}
+/**
+ * Wait for a dev server to signal readiness on stdout/stderr.
+ *
+ * Rejects (does NOT resolve) on timeout or process error — callers that
+ * need the server to be live for correctness (e.g. the review worker)
+ * must not proceed without a confirmed signal. If the server dies before
+ * becoming ready, we reject with the exit details.
+ */
 export declare function waitForDevServer(proc: ChildProcess, timeout: number): Promise<void>;
+/**
+ * Verify the dev server actually responds to HTTP GET before treating
+ * it as ready. Listening alone isn't enough — a framework can bind but
+ * still crash on the first request.
+ */
+export declare function probeDevServer(port: number, timeoutMs?: number): Promise<void>;

package/dist/verification.js

@@ -82,8 +82,15 @@ export async function runDeepReview(worktreePath, config, workerId) {
             cwd: worktreePath,
             stdio: ["ignore", "pipe", "pipe"],
         });
-        // Wait for dev server to be ready
-        await waitForDevServer(devServer, 30_000);
+        // Wait for dev server to be ready, then confirm it answers HTTP.
+        try {
+            await waitForDevServer(devServer, 30_000);
+            await probeDevServer(port);
+        }
+        catch (err) {
+            log.error(TAG, `Dev server did not become ready: ${err instanceof Error ? err.message : err}`);
+            return [];
+        }
         // Get diff for review context
         let diff = "";
         try {
@@ -217,35 +224,89 @@ function parseReviewFindings(output) {
         .map((l) => l.replace(/^\d+[.)]\s*/, ""))
         .filter((l) => l.length > 0);
 }
+export class DevServerReadinessError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "DevServerReadinessError";
+    }
+}
+/**
+ * Wait for a dev server to signal readiness on stdout/stderr.
+ *
+ * Rejects (does NOT resolve) on timeout or process error — callers that
+ * need the server to be live for correctness (e.g. the review worker)
+ * must not proceed without a confirmed signal. If the server dies before
+ * becoming ready, we reject with the exit details.
+ */
 export function waitForDevServer(proc, timeout) {
     return new Promise((resolve, reject) => {
+        let settled = false;
         const cleanup = () => {
             proc.stdout?.off("data", onData);
             proc.stderr?.off("data", onData);
             proc.off("error", onError);
+            proc.off("exit", onExit);
+            clearTimeout(timer);
         };
-        const timer = setTimeout(() => {
-            log.warn(TAG, "Dev server readiness not detected, proceeding anyway");
+        const settleResolve = () => {
+            if (settled)
+                return;
+            settled = true;
             cleanup();
             resolve();
+        };
+        const settleReject = (err) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(err);
+        };
+        const timer = setTimeout(() => {
+            settleReject(new DevServerReadinessError(`dev server did not signal readiness within ${timeout}ms`));
         }, timeout);
         const onData = (data) => {
             const text = data.toString();
             if (text.includes("ready") ||
                 text.includes("localhost") ||
                 text.includes("Local:")) {
-                clearTimeout(timer);
-                cleanup();
-                resolve();
+                settleResolve();
             }
         };
         const onError = (err) => {
-            clearTimeout(timer);
-            cleanup();
-            reject(err);
+            settleReject(err);
+        };
+        const onExit = (code, signal) => {
+            settleReject(new DevServerReadinessError(`dev server exited before becoming ready (code=${code ?? "?"}, signal=${signal ?? "?"})`));
         };
         proc.stdout?.on("data", onData);
         proc.stderr?.on("data", onData);
         proc.on("error", onError);
+        proc.on("exit", onExit);
     });
 }
+/**
+ * Verify the dev server actually responds to HTTP GET before treating
+ * it as ready. Listening alone isn't enough — a framework can bind but
+ * still crash on the first request.
+ */
+export async function probeDevServer(port, timeoutMs = 5000) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(`http://localhost:${port}/`, {
+            signal: controller.signal,
+        });
+        if (!res.ok && res.status >= 500) {
+            throw new DevServerReadinessError(`dev server returned ${res.status} on probe`);
+        }
+    }
+    catch (err) {
+        if (err instanceof DevServerReadinessError)
+            throw err;
+        throw new DevServerReadinessError(`dev server probe failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/watcher.d.ts

@@ -23,6 +23,8 @@ export declare class Watcher {
     private presenceChannel;
     private supabase;
     private daemonId;
+    private connected;
+    get isConnected(): boolean;
     constructor(credentials: RealtimeCredentials, projectId: string, onCardBroadcast: CardBroadcastHandler, onAgentCommand?: AgentCommandHandler | undefined);
     start(): Promise<void>;
     stop(): Promise<void>;

package/dist/watcher.js

@@ -16,6 +16,10 @@ export class Watcher {
     presenceChannel = null;
     supabase = null;
     daemonId = randomUUID();
+    connected = false;
+    get isConnected() {
+        return this.connected;
+    }
     constructor(credentials, projectId, onCardBroadcast, onAgentCommand) {
         this.credentials = credentials;
         this.projectId = projectId;
@@ -55,14 +59,20 @@ export class Watcher {
         })
             .subscribe((status) => {
             if (status === "SUBSCRIBED") {
+                this.connected = true;
                 log.info(TAG, "Broadcast subscription active");
             }
             else if (status === "CHANNEL_ERROR") {
+                this.connected = false;
                 log.error(TAG, "Broadcast channel error — will rely on reconciliation");
             }
             else if (status === "TIMED_OUT") {
+                this.connected = false;
                 log.warn(TAG, "Broadcast subscription timed out — retrying...");
             }
+            else if (status === "CLOSED") {
+                this.connected = false;
+            }
         });
         this.channel = channel;
         // Subscribe presence channel for daemon online indicator
@@ -94,6 +104,7 @@ export class Watcher {
             await this.supabase.realtime.disconnect();
             this.supabase = null;
         }
+        this.connected = false;
         log.info(TAG, "Broadcast subscription stopped");
     }
 }