@gethmy/agent 1.7.0 → 1.7.2

package/dist/stream-parser-selftest.js

@@ -1,97 +0,0 @@
-import { StreamParser } from "./stream-parser.js";
-/**
- * Feed a minimal Claude-CLI stream-json fixture through StreamParser and
- * assert the expected events fire. Intended as a startup canary: if the CLI
- * ever changes its envelope shape, the daemon fails loud on boot instead of
- * silently parking every card with a parse error (see card #128).
- *
- * Throws on any missing event; returns silently on success.
- */
-export function verifyStreamParserFormat() {
-    const parser = new StreamParser();
-    let textSeen = null;
-    let toolStart = null;
-    let toolEnd = null;
-    let resultSeen = null;
-    let costSeen = false;
-    parser.on("text", (c) => {
-        textSeen = c;
-    });
-    parser.on("tool_start", (name, input) => {
-        toolStart = { name, input };
-    });
-    parser.on("tool_end", (name, id, content) => {
-        toolEnd = { name, id, content };
-    });
-    parser.on("result", (stop) => {
-        resultSeen = stop;
-    });
-    parser.on("cost_update", () => {
-        costSeen = true;
-    });
-    const fixture = [
-        {
-            type: "assistant",
-            message: {
-                content: [{ type: "text", text: "canary-text" }],
-            },
-        },
-        {
-            type: "assistant",
-            message: {
-                content: [
-                    { type: "tool_use", id: "tu_canary", name: "Read", input: { x: 1 } },
-                ],
-            },
-        },
-        {
-            type: "user",
-            message: {
-                content: [
-                    {
-                        type: "tool_result",
-                        tool_use_id: "tu_canary",
-                        content: "ok",
-                    },
-                ],
-            },
-        },
-        {
-            type: "result",
-            subtype: "success",
-            result: "done",
-            stop_reason: "end_turn",
-            total_cost_usd: 0.001,
-            usage: { input_tokens: 1, output_tokens: 1 },
-        },
-    ];
-    for (const line of fixture) {
-        parser.feed(`${JSON.stringify(line)}\n`);
-    }
-    const failures = [];
-    if (textSeen !== "canary-text") {
-        failures.push(`text event missing or wrong (got ${JSON.stringify(textSeen)})`);
-    }
-    const ts = toolStart;
-    if (!ts || ts.name !== "Read") {
-        failures.push("tool_start event missing or wrong");
-    }
-    const te = toolEnd;
-    if (!te ||
-        te.name !== "Read" ||
-        te.id !== "tu_canary" ||
-        te.content !== "ok") {
-        failures.push("tool_end event missing or wrong");
-    }
-    if (resultSeen !== "end_turn") {
-        failures.push(`result event missing or wrong (got ${JSON.stringify(resultSeen)})`);
-    }
-    if (!costSeen) {
-        failures.push("cost_update event missing");
-    }
-    if (failures.length > 0) {
-        throw new Error("StreamParser canary failed — Claude CLI stream-json format may have drifted. " +
-            "Review pipeline will silently park every card until this is fixed.\n" +
-            failures.map((f) => `  - ${f}`).join("\n"));
-    }
-}

package/dist/stream-parser.d.ts

@@ -1,43 +0,0 @@
-import { EventEmitter } from "node:events";
-import type { Readable } from "node:stream";
-export interface CostUpdate {
-    totalCostUsd: number;
-    /** Fresh input tokens only — does NOT include cache_read or cache_creation. */
-    totalInputTokens: number;
-    totalOutputTokens: number;
-    totalCacheCreationInputTokens: number;
-    totalCacheReadInputTokens: number;
-    durationMs: number;
-    durationApiMs: number;
-    numTurns: number;
-    modelName?: string;
-}
-export interface StreamParserEvents {
-    tool_start: [name: string, input: unknown];
-    tool_end: [name: string, toolUseId: string, content: string | undefined];
-    text: [content: string];
-    result: [stopReason: string];
-    cost_update: [cost: CostUpdate];
-    parse_error: [msg: string];
-}
-export declare class StreamParser extends EventEmitter<StreamParserEvents> {
-    private buffer;
-    private attached;
-    private toolNames;
-    private hasEmittedText;
-    private observedModel?;
-    /**
-     * Attach a readable stream (Claude CLI stdout) to the parser.
-     * Parses NDJSON lines and emits typed events.
-     * Each instance must only be attached once.
-     */
-    attach(stream: Readable): void;
-    /**
-     * Feed a raw NDJSON chunk directly. Exposed for tests and any caller
-     * that doesn't have a Readable stream handy.
-     */
-    feed(chunk: string): void;
-    private flush;
-    private parseLine;
-    private handleMessage;
-}

package/dist/stream-parser.js

@@ -1,174 +0,0 @@
-import { EventEmitter } from "node:events";
-import { log } from "./log.js";
-const TAG = "stream-parser";
-export class StreamParser extends EventEmitter {
-    buffer = "";
-    attached = false;
-    toolNames = new Map();
-    hasEmittedText = false;
-    observedModel;
-    /**
-     * Attach a readable stream (Claude CLI stdout) to the parser.
-     * Parses NDJSON lines and emits typed events.
-     * Each instance must only be attached once.
-     */
-    attach(stream) {
-        if (this.attached) {
-            throw new Error("StreamParser already attached to a stream");
-        }
-        this.attached = true;
-        stream.on("data", (chunk) => {
-            this.buffer += chunk.toString();
-            this.flush();
-        });
-        stream.on("end", () => {
-            // Process any remaining buffer
-            if (this.buffer.trim()) {
-                this.flush();
-            }
-        });
-    }
-    /**
-     * Feed a raw NDJSON chunk directly. Exposed for tests and any caller
-     * that doesn't have a Readable stream handy.
-     */
-    feed(chunk) {
-        this.buffer += chunk;
-        this.flush();
-    }
-    flush() {
-        const lines = this.buffer.split("\n");
-        // Keep incomplete last line in buffer
-        this.buffer = lines.pop() ?? "";
-        for (const line of lines) {
-            const trimmed = line.trim();
-            if (!trimmed)
-                continue;
-            this.parseLine(trimmed);
-        }
-    }
-    parseLine(line) {
-        let msg;
-        try {
-            msg = JSON.parse(line);
-        }
-        catch {
-            // Not valid JSON — skip silently (could be stray output)
-            log.debug(TAG, `Non-JSON line: ${line.slice(0, 100)}`);
-            return;
-        }
-        try {
-            this.handleMessage(msg);
-        }
-        catch (err) {
-            const errMsg = err instanceof Error ? err.message : String(err);
-            log.warn(TAG, `Error handling stream event: ${errMsg}`);
-            this.emit("parse_error", errMsg);
-        }
-    }
-    handleMessage(msg) {
-        // Capture model from any envelope that carries it. The Claude CLI exposes
-        // `model` on the top-level `system` envelope and inside each assistant
-        // envelope's message, but the final `result` envelope does not.
-        if (!this.observedModel) {
-            if (typeof msg.model === "string") {
-                this.observedModel = msg.model;
-            }
-            else if (typeof msg.message?.model === "string") {
-                this.observedModel = msg.message.model;
-            }
-        }
-        switch (msg.type) {
-            case "assistant": {
-                const blocks = msg.message?.content;
-                if (!Array.isArray(blocks))
-                    break;
-                for (const block of blocks) {
-                    if (block.type === "text" && typeof block.text === "string") {
-                        this.emit("text", block.text);
-                        this.hasEmittedText = true;
-                    }
-                    else if (block.type === "tool_use" &&
-                        typeof block.name === "string") {
-                        if (typeof block.id === "string") {
-                            this.toolNames.set(block.id, block.name);
-                        }
-                        this.emit("tool_start", block.name, block.input);
-                    }
-                    // thinking blocks, redacted_thinking, etc. — ignored
-                }
-                break;
-            }
-            case "user": {
-                const blocks = msg.message?.content;
-                if (!Array.isArray(blocks))
-                    break;
-                for (const block of blocks) {
-                    if (block.type === "tool_result" &&
-                        typeof block.tool_use_id === "string") {
-                        const name = this.toolNames.get(block.tool_use_id) ?? "";
-                        this.toolNames.delete(block.tool_use_id);
-                        const content = normalizeToolResultContent(block.content);
-                        this.emit("tool_end", name, block.tool_use_id, content);
-                    }
-                }
-                break;
-            }
-            case "result": {
-                // Fallback: if the CLI ended without streaming any assistant text
-                // (e.g. hit max-turns), the final `result` field still carries the
-                // last assistant message. Emit it so the caller can parse the verdict.
-                if (!this.hasEmittedText &&
-                    typeof msg.result === "string" &&
-                    msg.result.length > 0) {
-                    this.emit("text", msg.result);
-                    this.hasEmittedText = true;
-                }
-                if (typeof msg.total_cost_usd === "number") {
-                    const usage = msg.usage;
-                    this.emit("cost_update", {
-                        totalCostUsd: msg.total_cost_usd,
-                        totalInputTokens: usage?.input_tokens ?? 0,
-                        totalOutputTokens: usage?.output_tokens ?? 0,
-                        totalCacheCreationInputTokens: usage?.cache_creation_input_tokens ?? 0,
-                        totalCacheReadInputTokens: usage?.cache_read_input_tokens ?? 0,
-                        durationMs: msg.duration_ms ?? 0,
-                        durationApiMs: msg.duration_api_ms ?? 0,
-                        numTurns: msg.num_turns ?? 0,
-                        modelName: this.observedModel ??
-                            (typeof msg.model === "string" ? msg.model : undefined),
-                    });
-                }
-                this.emit("result", msg.stop_reason ?? msg.subtype ?? "unknown");
-                break;
-            }
-            // Ignore system, ping, etc.
-        }
-    }
-}
-function normalizeToolResultContent(raw) {
-    if (raw == null)
-        return undefined;
-    if (typeof raw === "string")
-        return raw;
-    if (Array.isArray(raw)) {
-        // Anthropic sometimes returns content as a list of typed blocks
-        // ({ type: "text", text: "..." }); flatten text blocks, fall back to JSON.
-        const parts = [];
-        for (const block of raw) {
-            if (block &&
-                typeof block === "object" &&
-                "text" in block &&
-                typeof block.text === "string") {
-                parts.push(block.text);
-            }
-        }
-        return parts.length > 0 ? parts.join("") : JSON.stringify(raw);
-    }
-    try {
-        return JSON.stringify(raw);
-    }
-    catch {
-        return String(raw);
-    }
-}

package/dist/transitions.d.ts

@@ -1,57 +0,0 @@
-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

@@ -1,131 +0,0 @@
-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

@@ -1,140 +0,0 @@
-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;
-        reviewModel: string;
-        maxTurns: number;
-        additionalArgs: string[];
-    };
-    worktree: {
-        basePath: string;
-        baseBranch: string;
-        /** Remote-branch prefix while an attempt is still in-flight or failed. */
-        failedBranchPrefix: string;
-        /** Remote-branch prefix after a successful run reaches Review. */
-        approvedBranchPrefix: string;
-        /** Days to keep failed-attempt branches on origin before GC removes them. */
-        failedAttemptRetentionDays: number;
-    };
-    verification: {
-        enabled: boolean;
-        build: boolean;
-        lint: boolean;
-        autoFix: boolean;
-        maxFixAttempts: number;
-        deepReview: boolean;
-        devServerBasePort: number;
-        timeout: number;
-        failColumn: string;
-    };
-    review: {
-        enabled: boolean;
-        /** Concurrent review workers. Each gets its own dev-server port slot. */
-        poolSize: number;
-        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;
-    };
-    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";
-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;
-}
-/** Pipeline that produced an episode. */
-export type EpisodeKind = "implement" | "review";
-/** Outcome of an implement run; review verdict maps to its own type. */
-export type EpisodeOutcome = "success" | "failure";
-/**
- * Structured metadata persisted alongside every episode entity in
- * `knowledge_entities.metadata`. Read by the recall path to render the
- * "Similar past tasks" section in subsequent agent prompts.
- */
-export interface EpisodeMeta {
-    episode_kind: EpisodeKind;
-    card_short_id: number;
-    card_title: string;
-    approach_summary: string;
-    outcome: EpisodeOutcome;
-    quality_score: number;
-    duration_ms: number;
-    token_cost: {
-        input: number;
-        output: number;
-        usd: number;
-    };
-    files_touched: number;
-    num_turns: number;
-    error?: string;
-    /** Provenance only — never used as memory scope. */
-    agent_session_id?: string;
-    /** Set on back-fill from review pipeline. */
-    review_session_id?: string;
-    /** Set on review-decision entities so back-fill can find the original. */
-    original_episode_id?: string;
-}