@gethmy/harness 1.0.0

package/src/harmony-client.ts

@@ -0,0 +1,197 @@
+/**
+ * The motor's only door to Harmony: read the one card it was invoked for, read
+ * that card's pinned stage definition, fetch a held oracle, record gate
+ * evidence. Nothing else — the motor does not read the board, does not advance
+ * a stage, and does not decide what runs next.
+ *
+ * The card read is deliberately NARROW: `fetchStageCard` returns exactly
+ * `current_stage`, `playbook_id` and `playbook_version` and drops every other
+ * field the API sends, so no board content (title, description, comments) can
+ * flow onward from here — not into a prompt, not into a log. Those three fields
+ * exist because `resolveStageGate` (gate-collectors.ts) takes a card, not a
+ * request: it needs the PIN to read the frozen stage definition the gate is
+ * collected against. Passing `playbook_id` / `playbook_version` as CLI flags
+ * instead would move the read into the driver and make the pin forgeable by the
+ * caller.
+ *
+ * `request` is the generic seam `resolveStageGate` consumes
+ * (`(method, path) => Promise<{ version: … }>`). It THROWS on a non-ok status.
+ * `fetchOracle` deliberately does not: a denied or missing oracle returns null
+ * so the collector reports `blocked`. A gate with no signal must never read as
+ * a pass, and after ruling 27 a 403 also means "this caller does not own the
+ * run", which is exactly the signal worth logging loudly.
+ *
+ * Auth is the `X-API-Key` header, which is what harmony-api reads for an
+ * agent/API key (`supabase/functions/harmony-api/index.ts`; the same header
+ * also carries an OAuth access token when it starts with `hmy_at_`). An
+ * `authorization: Bearer` header would fall through to the Supabase-JWT path
+ * and 401. `packages/mcp-server/src/api-client.ts` sends the same header, and
+ * this client mirrors its URL shape too: `HARMONY_API_URL` is the API BASE
+ * (e.g. `https://app.gethmy.com/api`) and `/v1` is appended per request.
+ */
+import type { Card, StageGateEvidenceInsert } from "@harmony/shared";
+import { log } from "./log.js";
+import type { HeldOracle } from "./oracle.js";
+
+const TAG = "harmony-client";
+
+export interface HarmonyClientConfig {
+  apiUrl: string;
+  apiKey: string;
+}
+
+/**
+ * The three card fields the motor reads, and the only ones it keeps. Typed off
+ * `Card` so a rename in the shared model breaks this compile rather than
+ * silently producing an unresolvable pin.
+ */
+export type StageCardPin = Pick<
+  Card,
+  "current_stage" | "playbook_id" | "playbook_version"
+>;
+
+/** The oracle payload `POST /stage-oracle/fetch` returns (camelCase, edge-side). */
+interface OracleResponse {
+  path: string;
+  content: string;
+  runnerHint?: string | null;
+}
+
+export function readClientConfig(
+  env: Record<string, string | undefined>,
+): HarmonyClientConfig {
+  const apiUrl = env.HARMONY_API_URL?.trim();
+  const apiKey = env.HARMONY_API_KEY?.trim();
+  if (!apiUrl) {
+    throw new Error(
+      "HARMONY_API_URL is not set — the motor needs the Harmony API base URL (e.g. https://app.gethmy.com/api)",
+    );
+  }
+  if (!apiKey) {
+    throw new Error(
+      "HARMONY_API_KEY is not set — the motor needs a Harmony API key or OAuth access token",
+    );
+  }
+  // Trim trailing slashes so the built path has exactly one separator. A blank
+  // value is refused above rather than sent: an empty credential would 401 at
+  // the edge with no hint about which end is misconfigured.
+  return { apiUrl: apiUrl.replace(/\/+$/, ""), apiKey };
+}
+
+export class HarmonyClient {
+  constructor(private readonly config: HarmonyClientConfig) {}
+
+  /** One raw call. Returns the Response so a caller can judge the status itself. */
+  private async send(
+    method: string,
+    path: string,
+    body?: unknown,
+  ): Promise<Response> {
+    return await fetch(`${this.config.apiUrl}/v1${path}`, {
+      method,
+      headers: {
+        "X-API-Key": this.config.apiKey,
+        "content-type": "application/json",
+        accept: "application/json",
+      },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    });
+  }
+
+  /**
+   * The generic request seam. `resolveStageGate` reads the pinned
+   * `playbook_versions` snapshot through this; `fetchStageCard` uses it too.
+   * Throws on a non-ok status — the caller that must not throw (`fetchOracle`)
+   * uses {@link send} directly instead.
+   */
+  async request<T>(method: string, path: string, body?: unknown): Promise<T> {
+    const response = await this.send(method, path, body);
+    if (!response.ok) {
+      throw new Error(
+        `${method} ${path} failed with ${response.status}${await detail(response)}`,
+      );
+    }
+    return (await response.json()) as T;
+  }
+
+  /**
+   * Read the card's stage pin. Only the three pinned fields survive this
+   * function — see the module doc comment for why the read exists at all and
+   * why it stops there.
+   */
+  async fetchStageCard(cardId: string): Promise<StageCardPin> {
+    const { card } = await this.request<{ card: StageCardPin }>(
+      "GET",
+      `/cards/${encodeURIComponent(cardId)}`,
+    );
+    return {
+      current_stage: card.current_stage ?? null,
+      playbook_id: card.playbook_id ?? null,
+      playbook_version: card.playbook_version ?? null,
+    };
+  }
+
+  /**
+   * Fetch the held oracle for `stageId`. The session id travels in the body
+   * beside `purpose: "gate_evaluation"` — the read route binds the caller to the
+   * card's ACTIVE agent session (ruling 27), so an ended or foreign session is a
+   * 403.
+   *
+   * ANY non-ok status returns null, not just 403/404: the collector turns null
+   * into `blocked`, which is the honest outcome for "no oracle was read" whatever
+   * the reason. The status itself is logged here, because the collector's
+   * `blocked` reason cannot distinguish a refusal from an absence.
+   */
+  async fetchOracle(
+    cardId: string,
+    stageId: string,
+    sessionId: string,
+  ): Promise<HeldOracle | null> {
+    const response = await this.send("POST", "/stage-oracle/fetch", {
+      cardId,
+      stageId,
+      sessionId,
+      purpose: "gate_evaluation",
+    });
+    if (!response.ok) {
+      log.warn(
+        TAG,
+        `Oracle fetch for stage ${stageId} returned ${response.status} — no oracle read, the gate will report blocked`,
+      );
+      return null;
+    }
+    const body = (await response.json()) as OracleResponse;
+    return {
+      path: body.path,
+      content: body.content,
+      runnerHint: body.runnerHint ?? null,
+    };
+  }
+
+  /**
+   * Persist one evidence row. The card id in the insert IS the id in the route's
+   * path (`POST /cards/:cardId/stage-gate-evidence`) — the same shape
+   * `packages/mcp-server/src/api-client.ts` uses. Throws on a refused write:
+   * the stored row is what the human-advance edge re-evaluates, so a lost row
+   * must never read as a recorded one.
+   */
+  async recordStageGateEvidence(
+    insert: StageGateEvidenceInsert,
+  ): Promise<void> {
+    await this.request(
+      "POST",
+      `/cards/${encodeURIComponent(insert.card_id)}/stage-gate-evidence`,
+      insert,
+    );
+  }
+}
+
+/** Best-effort error detail for a failed request. Never throws. */
+async function detail(response: Response): Promise<string> {
+  try {
+    const text = await response.text();
+    return text ? `: ${text.slice(0, 500)}` : "";
+  } catch {
+    return "";
+  }
+}

package/src/index.ts

@@ -0,0 +1,37 @@
+/**
+ * Public surface of the Harmony execution motor.
+ *
+ * The motor runs exactly ONE playbook stage per invocation and exits. It owns the
+ * worktree, dispatches the subagent for the stage's role, places and removes the
+ * held oracle, and collects gate evidence. It deliberately does NOT decide which
+ * stage runs next (Harmony does), does NOT form a gate verdict (`gateEvaluate` in
+ * @harmony/shared does), and does NOT push or merge.
+ *
+ * Dependency direction is agent → harness → shared. Importing from @gethmy/agent
+ * here would create a cycle and is never correct.
+ */
+export const MOTOR_NAME = "harmony-harness";
+
+export * from "./artifact-judge.js";
+export * from "./command-metric.js";
+export * from "./error-classifier.js";
+export * from "./exec-types.js";
+export * from "./gate-collectors.js";
+export * from "./gate-config-error.js";
+export * from "./git-diff-stat.js";
+export * from "./git-pr.js";
+export * from "./harmony-client.js";
+export * from "./log.js";
+export * from "./model-tier.js";
+export * from "./oracle.js";
+export * from "./oracle-collector.js";
+export * from "./pm.js";
+export * from "./process-group.js";
+export * from "./project-type.js";
+export * from "./revert-guard.js";
+export * from "./review-types.js";
+export * from "./runner.js";
+export * from "./sdk-agent-runner.js";
+export * from "./stage-run.js";
+export * from "./verification.js";
+export * from "./worktree.js";

package/src/log.ts

@@ -0,0 +1,129 @@
+/**
+ * Structured logging for the agent daemon.
+ *
+ * When stderr is a TTY, output is ANSI-coloured single-line text — the
+ * readable default for humans running the daemon interactively. When
+ * stderr is piped/redirected (files, logshippers, systemd), output
+ * falls back to one JSON object per line — trivially `jq`-able,
+ * indexable, and machine-readable.
+ *
+ * Overrides: `--pretty` / HARMONY_AGENT_PRETTY=1 force pretty;
+ * `--json`   / HARMONY_AGENT_JSON=1   force JSON. Explicit flags beat
+ * TTY detection either way.
+ *
+ * Stdout is left clean so consumers can pipe structured data if they
+ * want to (future use).
+ */
+
+type Level = "debug" | "info" | "warn" | "error";
+
+export interface LogContext {
+  event?: string;
+  runId?: string;
+  cardId?: string;
+  [key: string]: unknown;
+}
+
+interface LogRecord extends LogContext {
+  ts: string;
+  level: Level;
+  tag: string;
+  msg: string;
+}
+
+const COLORS = {
+  reset: "\x1b[0m",
+  dim: "\x1b[2m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  cyan: "\x1b[36m",
+} as const;
+
+const LEVEL_COLOR: Record<Level, string> = {
+  debug: COLORS.dim,
+  info: COLORS.green,
+  warn: COLORS.yellow,
+  error: COLORS.red,
+};
+
+function pretty(): boolean {
+  if (
+    process.env.HARMONY_AGENT_JSON === "1" ||
+    process.argv.includes("--json")
+  ) {
+    return false;
+  }
+  if (process.env.HARMONY_AGENT_PRETTY === "1") return true;
+  if (process.argv.includes("--pretty")) return true;
+  return Boolean(process.stderr.isTTY);
+}
+
+function shortTime(iso: string): string {
+  return iso.slice(11, 23);
+}
+
+function emit(rec: LogRecord): void {
+  if (rec.level === "debug" && !process.env.DEBUG) return;
+
+  if (pretty()) {
+    const color = LEVEL_COLOR[rec.level];
+    const label = rec.level.toUpperCase().padEnd(5, " ");
+    const ctx: string[] = [];
+    if (rec.event) ctx.push(`event=${rec.event}`);
+    if (rec.runId) ctx.push(`run=${rec.runId}`);
+    if (rec.cardId) ctx.push(`card=${rec.cardId}`);
+    const tail = ctx.length
+      ? ` ${COLORS.dim}(${ctx.join(" ")})${COLORS.reset}`
+      : "";
+    process.stderr.write(
+      `${COLORS.dim}${shortTime(rec.ts)}${COLORS.reset} ${color}${label}${COLORS.reset} ${COLORS.cyan}[${rec.tag}]${COLORS.reset} ${rec.msg}${tail}\n`,
+    );
+    return;
+  }
+
+  process.stderr.write(`${JSON.stringify(rec)}\n`);
+}
+
+function record(
+  level: Level,
+  tag: string,
+  msg: string,
+  ctx?: LogContext,
+): void {
+  const rec: LogRecord = {
+    ts: new Date().toISOString(),
+    level,
+    tag,
+    msg,
+    ...(ctx ?? {}),
+  };
+  emit(rec);
+}
+
+export const log = {
+  info(tag: string, msg: string, ctx?: LogContext) {
+    record("info", tag, msg, ctx);
+  },
+  warn(tag: string, msg: string, ctx?: LogContext) {
+    record("warn", tag, msg, ctx);
+  },
+  error(tag: string, msg: string, ctx?: LogContext) {
+    record("error", tag, msg, ctx);
+  },
+  debug(tag: string, msg: string, ctx?: LogContext) {
+    record("debug", tag, msg, ctx);
+  },
+  /**
+   * Emit a named event. Semantically the same as `info` but signals to
+   * downstream tooling that this is a structured event worth indexing.
+   */
+  event(tag: string, event: string, ctx?: LogContext) {
+    record("info", tag, event, { ...ctx, event });
+  },
+};
+
+export function isPretty(): boolean {
+  return pretty();
+}

package/src/model-tier.test.ts

@@ -0,0 +1,169 @@
+import type { Card } from "@harmony/shared";
+import { escalateTier, tierFromScore } from "@harmony/shared";
+import { describe, expect, it } from "vitest";
+import {
+  chooseImplementModel,
+  MAX_IMPLEMENT_MODEL,
+  type ModelTierConfig,
+} from "./model-tier.js";
+
+const claude: ModelTierConfig = {
+  model: "opus",
+  escalateModel: "claude-opus-4-8",
+  escalateAfterAttempts: 2,
+  tiers: { simple: "haiku", advanced: "sonnet", research: "opus" },
+};
+
+function card(p: Partial<Card>): Card {
+  return {
+    priority: "medium",
+    model_tier: null,
+    model_override: null,
+    ...p,
+  } as Card;
+}
+
+describe("tierFromScore", () => {
+  it("maps score ranges to tiers and clamps", () => {
+    expect(tierFromScore(0)).toBe("simple");
+    expect(tierFromScore(2)).toBe("simple");
+    expect(tierFromScore(3)).toBe("advanced");
+    expect(tierFromScore(6)).toBe("advanced");
+    expect(tierFromScore(7)).toBe("research");
+    expect(tierFromScore(99)).toBe("research");
+    expect(tierFromScore(-5)).toBe("simple");
+  });
+});
+
+describe("escalateTier", () => {
+  it("bumps one level, capping at research", () => {
+    expect(escalateTier("simple")).toBe("advanced");
+    expect(escalateTier("advanced")).toBe("research");
+    expect(escalateTier("research")).toBe("research");
+  });
+});
+
+describe("chooseImplementModel", () => {
+  it("honors a pinned override above everything (no escalation)", () => {
+    const r = chooseImplementModel(
+      claude,
+      card({
+        model_override: "claude-opus-4-8",
+        model_tier: "simple",
+        priority: "urgent",
+      }),
+      5,
+    );
+    expect(r).toEqual({
+      model: "claude-opus-4-8",
+      escalated: false,
+      source: "override",
+    });
+  });
+
+  it("resolves a tier to its configured model on the first attempt", () => {
+    const r = chooseImplementModel(claude, card({ model_tier: "simple" }), 1);
+    expect(r).toEqual({ model: "haiku", escalated: false, source: "tier" });
+  });
+
+  it("escalates the tier up one level on a retry", () => {
+    const r = chooseImplementModel(claude, card({ model_tier: "simple" }), 2);
+    expect(r).toEqual({ model: "sonnet", escalated: true, source: "tier" });
+  });
+
+  it("falls back to global policy when no tier/override is set", () => {
+    expect(chooseImplementModel(claude, card({}), 1)).toEqual({
+      model: "opus",
+      escalated: false,
+      source: "policy",
+    });
+    expect(chooseImplementModel(claude, card({}), 2)).toEqual({
+      model: "claude-opus-4-8",
+      escalated: true,
+      source: "policy",
+    });
+    expect(chooseImplementModel(claude, card({ priority: "high" }), 1)).toEqual(
+      { model: "claude-opus-4-8", escalated: true, source: "policy" },
+    );
+  });
+
+  it("spawns Fable 5 unclamped now that it is available again (#747)", () => {
+    // Pinned override.
+    expect(
+      chooseImplementModel(
+        claude,
+        card({ model_override: "claude-fable-5" }),
+        1,
+      ),
+    ).toEqual({
+      model: "claude-fable-5",
+      escalated: false,
+      source: "override",
+    });
+
+    // Global policy escalation (the shipped default).
+    const fableEscalate = { ...claude, escalateModel: "claude-fable-5" };
+    expect(chooseImplementModel(fableEscalate, card({}), 2)).toEqual({
+      model: "claude-fable-5",
+      escalated: true,
+      source: "policy",
+    });
+
+    // Tier mapping.
+    const fableTier = {
+      ...claude,
+      tiers: {
+        simple: "haiku",
+        advanced: "sonnet",
+        research: "claude-fable-5",
+      },
+    };
+    expect(
+      chooseImplementModel(fableTier, card({ model_tier: "research" }), 1)
+        .model,
+    ).toBe("claude-fable-5");
+  });
+
+  it("clamps a retired model id up to the ceiling from any source", () => {
+    // Pinned override naming a retired model.
+    expect(
+      chooseImplementModel(
+        claude,
+        card({ model_override: "claude-3-5-sonnet-20241022" }),
+        1,
+      ),
+    ).toEqual({
+      model: MAX_IMPLEMENT_MODEL,
+      escalated: false,
+      source: "override",
+    });
+
+    // Stale config still pointing escalateModel at a retired model.
+    const staleConfig = { ...claude, escalateModel: "claude-3-opus-20240229" };
+    expect(chooseImplementModel(staleConfig, card({}), 2)).toEqual({
+      model: MAX_IMPLEMENT_MODEL,
+      escalated: true,
+      source: "policy",
+    });
+
+    // Tier mapping pointing at a retired model.
+    const retiredTier = {
+      ...claude,
+      tiers: { simple: "claude-2.1", advanced: "sonnet", research: "opus" },
+    };
+    expect(
+      chooseImplementModel(retiredTier, card({ model_tier: "simple" }), 1)
+        .model,
+    ).toBe(MAX_IMPLEMENT_MODEL);
+  });
+
+  it("falls back to base model if a tier has no configured mapping", () => {
+    const r = chooseImplementModel(
+      { ...claude, tiers: { simple: "", advanced: "", research: "" } },
+      card({ model_tier: "research" }),
+      1,
+    );
+    expect(r.model).toBe("opus");
+    expect(r.source).toBe("tier");
+  });
+});

package/src/model-tier.ts

@@ -0,0 +1,108 @@
+import type { Card } from "@harmony/shared";
+import { escalateTier, isModelTier } from "@harmony/shared";
+
+/**
+ * The narrow slice of `AgentConfig["claude"]` that {@link chooseImplementModel}
+ * actually reads. The daemon's `AgentConfig` carries fields this module never
+ * touches (`reviewModel`, `maxTurns`, `leanSettingSources`, …); importing the
+ * whole daemon type would pull `harness → agent`, which the dependency
+ * direction (agent → harness → shared) forbids. `VerificationConfig.claude` in
+ * `exec-types.ts` is a *different* narrow slice of the same daemon field — two
+ * narrow types over the same source, each declaring only what its consumer
+ * reads.
+ */
+export interface ModelTierConfig {
+  model: string;
+  escalateModel: string;
+  escalateAfterAttempts: number;
+  tiers: { simple: string; advanced: string; research: string };
+}
+
+/**
+ * Hard ceiling for any implement run: Fable 5, the most capable model the
+ * daemon may spawn — nothing escalates past it. Also the substitute a retired
+ * model id is clamped to (see {@link clampWithdrawn}).
+ *
+ * Fable 5 was previously withdrawn from availability, which is why this used to
+ * point at Opus 4.8 and the clamp below matched `/fable/`. It is generally
+ * available again (#747), so it is once more the top of the ladder.
+ */
+export const MAX_IMPLEMENT_MODEL = "claude-fable-5";
+
+/**
+ * Retired model ids that must never reach the Claude CLI. Every `claude-2.x`
+ * and `claude-3.x` id has now passed its retirement date (the last one,
+ * `claude-3-haiku-20240307`, retired 2026-04-19), so the whole 2/3 generation
+ * 404s on the API. The 4.x family is still served and is deliberately NOT
+ * matched — an operator pinning Opus 4.8 gets Opus 4.8.
+ */
+const RETIRED_MODEL = /^claude-[23][.-]/i;
+
+/**
+ * Clamp a requested model up to {@link MAX_IMPLEMENT_MODEL} if it names a
+ * retired model. Applied to every resolution path (pinned override, tier
+ * mapping, global policy) so a stale `config.json` or a manually-pinned card
+ * can't spawn a model that no longer exists.
+ *
+ * Exported so the #517 artifact judge clamps its lean tier through the same gate
+ * (a stale judge model id can't reach the SDK either).
+ */
+export function clampWithdrawn(model: string): string {
+  return RETIRED_MODEL.test(model) ? MAX_IMPLEMENT_MODEL : model;
+}
+
+/**
+ * Pick the model for an implement run.
+ *
+ * Precedence (#354):
+ *   1. `card.model_override` — a user-pinned concrete model id. Always wins,
+ *      never auto-escalates (the user chose it deliberately).
+ *   2. `card.model_tier` — the classifier's suggested tier, resolved through
+ *      `claude.tiers`. On a retry (attempts >= escalateAfterAttempts) the tier
+ *      bumps up one level before resolving.
+ *   3. Global policy fallback — the original #348 behaviour: escalate to
+ *      `escalateModel` on high/urgent priority or on a retry, else `model`.
+ *
+ * Whichever path wins, the result is clamped to {@link MAX_IMPLEMENT_MODEL}:
+ * a retired model id is never spawned regardless of its source.
+ *
+ * Pure so the policy is unit-testable without spawning a worker.
+ */
+export function chooseImplementModel(
+  claude: ModelTierConfig,
+  card: Pick<Card, "priority" | "model_tier" | "model_override">,
+  attempts: number,
+): {
+  model: string;
+  escalated: boolean;
+  source: "override" | "tier" | "policy";
+} {
+  if (card.model_override) {
+    return {
+      model: clampWithdrawn(card.model_override),
+      escalated: false,
+      source: "override",
+    };
+  }
+
+  if (isModelTier(card.model_tier)) {
+    const retry = attempts >= claude.escalateAfterAttempts;
+    const tier = retry ? escalateTier(card.model_tier) : card.model_tier;
+    const mapped = claude.tiers?.[tier];
+    return {
+      model: clampWithdrawn(
+        mapped && mapped.length > 0 ? mapped : claude.model,
+      ),
+      escalated: retry,
+      source: "tier",
+    };
+  }
+
+  const highPriority = card.priority === "high" || card.priority === "urgent";
+  const escalated = highPriority || attempts >= claude.escalateAfterAttempts;
+  return {
+    model: clampWithdrawn(escalated ? claude.escalateModel : claude.model),
+    escalated,
+    source: "policy",
+  };
+}