@gethmy/harness 1.0.0

package/src/stage-cli.ts

@@ -0,0 +1,302 @@
+/**
+ * The stage-run CLI's decidable parts: argument validation, the fail-loud stage
+ * check, the pinned-stage resolution, the subagent's prompt, and the runner
+ * config that carries the role's two enforcement fields. No network and no
+ * subprocess here — `cli.ts` stays a thin shell around the IO, and every rule
+ * below is testable without a live API.
+ *
+ * `buildStageRunnerConfig` exists as a seam for exactly one reason: the tool
+ * deny and the credential strip would otherwise be assembled inline in
+ * `cli.ts`, the one file no test executes, where deleting either line leaves
+ * the whole suite green while a documented security property quietly stops
+ * holding.
+ */
+import {
+  type GateSpec,
+  isAgentRunnableOwner,
+  type PlaybookStageDef,
+  type PlaybookStageRole,
+  type PlaybookVersionDef,
+  resolveStageDef,
+} from "@harmony/shared";
+import { normalizeGateSpec } from "./gate-collectors.js";
+import type { StageCardPin } from "./harmony-client.js";
+import { buildRoleLaunch, envKeysDroppedByLaunch } from "./runner.js";
+import type { SdkRunnerConfig } from "./sdk-agent-runner.js";
+
+export const STAGE_RUN_USAGE =
+  "usage: harmony-harness stage run --card <id> --stage <id> --workspace <id> --repo <path> --session <id> [--metrics <json-path>]";
+
+/** The five identifiers one stage run needs. Every one is required.
+ * `metricsPath` is the one optional input: a JSON file holding the DRIVER's
+ * metric allowlist for `custom` gates (same shape as the daemon operator's
+ * `agent.playbooks.metrics`). The motor itself stays config-free — without the
+ * flag a `custom` gate reports "metric not declared" and blocks, exactly as
+ * before. */
+export interface StageRunArgs {
+  cardId: string;
+  stageId: string;
+  workspaceId: string;
+  repoPath: string;
+  sessionId: string;
+  metricsPath: string | null;
+}
+
+export type StageRunArgsResult =
+  | { ok: true; args: StageRunArgs }
+  | { ok: false; message: string };
+
+/**
+ * Read one `--flag value` pair. A flag whose value is absent, blank, or another
+ * flag is REFUSED rather than defaulted: `--session --repo /tmp/wt` would
+ * otherwise send "--repo" (or an empty string) as the agent-session id, and the
+ * oracle read route would refuse it with a 403 that names nothing useful.
+ */
+function readFlag(argv: string[], name: string): string | null {
+  const index = argv.indexOf(`--${name}`);
+  if (index === -1) return null;
+  const value = argv[index + 1];
+  if (value === undefined || value.startsWith("--")) return null;
+  // Return the TRIMMED value: a padded `--card " card-1 "` would otherwise be
+  // handed to `encodeURIComponent` and reach the API as "%20card-1%20", which
+  // matches no card and reports as a plain 404.
+  const trimmed = value.trim();
+  return trimmed.length === 0 ? null : trimmed;
+}
+
+/**
+ * Validate an `argv` (already stripped of `node` and the script path). Returns
+ * the five identifiers, or a message naming the first flag that is missing —
+ * the caller exits 2 with the usage line.
+ */
+export function parseStageRunArgs(argv: string[]): StageRunArgsResult {
+  if (argv[0] !== "stage" || argv[1] !== "run") {
+    return {
+      ok: false,
+      message: `unknown command "${argv.slice(0, 2).join(" ")}" — the motor runs exactly one thing: stage run`,
+    };
+  }
+
+  const fields: Array<[Exclude<keyof StageRunArgs, "metricsPath">, string]> = [
+    ["cardId", "card"],
+    ["stageId", "stage"],
+    ["workspaceId", "workspace"],
+    ["repoPath", "repo"],
+    ["sessionId", "session"],
+  ];
+  const args = { metricsPath: null } as StageRunArgs;
+  for (const [field, flag] of fields) {
+    const value = readFlag(argv, flag);
+    if (value === null) {
+      return { ok: false, message: `missing --${flag} <value>` };
+    }
+    args[field] = value;
+  }
+
+  // Optional: --metrics <path>. Distinguish "absent" (fine — custom gates
+  // block with a legible reason) from "present but valueless" (refused — the
+  // driver clearly meant to pass an allowlist and silently running without one
+  // would turn every custom gate into a block the driver did not expect).
+  if (argv.includes("--metrics")) {
+    const metricsPath = readFlag(argv, "metrics");
+    if (metricsPath === null) {
+      return { ok: false, message: "missing value for --metrics <json-path>" };
+    }
+    args.metricsPath = metricsPath;
+  }
+  return { ok: true, args };
+}
+
+/**
+ * Parse the driver's metric-allowlist file (`--metrics`). THROWS on an
+ * unreadable file, invalid JSON, or a non-object top level — a driver that
+ * passed the flag wants the allowlist applied, and degrading to `{}` would
+ * silently turn every `custom` gate into a block. Per-metric validation stays
+ * where it lives: the command collector fails closed on a malformed
+ * declaration and names the key to fix.
+ */
+export function parseMetricsAllowlist(
+  raw: string,
+  sourcePath: string,
+): Record<string, unknown> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `--metrics ${sourcePath} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error(
+      `--metrics ${sourcePath} must hold a JSON object keyed by metric name`,
+    );
+  }
+  return parsed as Record<string, unknown>;
+}
+
+/**
+ * Refuse to run when the CLI's `--stage` disagrees with the card's
+ * `current_stage`. THROWS — the motor collects nothing in that case.
+ *
+ * Collecting evidence for a stage the card is not on writes a row that
+ * `gateEvaluate` later applies to a DIFFERENT stage. Silently preferring either
+ * side would hide a driver/board desync, which is the same acting-vs-named
+ * stage confusion the API had to untangle for the oracle routes.
+ */
+export function assertCardOnStage(stageId: string, card: StageCardPin): void {
+  if (card.current_stage === stageId) return;
+  throw new Error(
+    `--stage "${stageId}" does not match the card's current_stage ${
+      card.current_stage === null ? "(none)" : `"${card.current_stage}"`
+    } — refusing to collect evidence for a stage the card is not on`,
+  );
+}
+
+/**
+ * Refuse to run a stage a HUMAN owns. THROWS — before any subagent is launched
+ * and before anything is written.
+ *
+ * `owner` is the stage model's answer to "who runs this stage?", and `human`
+ * means a person does. Until this check existed nothing under
+ * `packages/harmony-harness/src/` read `owner` at all, so a driver that handed
+ * the motor a human stage would get a subagent doing that person's work and a
+ * gate collected against it — the card would look advanced by a human who never
+ * saw it. `fix-a-bug` stage 3 (`Review`) is `owner: "human"`, so this is
+ * reachable the moment a driver exists, not a hypothetical.
+ *
+ * The spec's rule for both drivers is that reaching a human stage is a NORMAL
+ * outcome — write `stage_waiting` and stop — so the refusal belongs to the
+ * driver's decision, and the motor's job is only to make running one impossible
+ * by accident. Same shape as {@link assertCardOnStage}: fail loud, name what
+ * disagrees, collect nothing. `either` and `agent` both run
+ * (`isAgentRunnableOwner`), which is the same predicate the daemon's stage
+ * executor already uses — one rule, not a second opinion.
+ */
+export function assertStageIsAgentRunnable(stage: PlaybookStageDef): void {
+  if (isAgentRunnableOwner(stage.owner)) return;
+  throw new Error(
+    `stage "${stage.id}" ("${stage.name}") is owned by "${stage.owner}" — refusing to run a stage a human owns`,
+  );
+}
+
+/**
+ * The subagent's prompt. Built from the stage's `entry_action` when the pinned
+ * stage names one, otherwise from the card — in which case the agent is told to
+ * read the card itself through the Harmony MCP tools, which every role keeps
+ * (see runner.ts). The motor does not read board content to build this.
+ *
+ * The signature is the guard on what can leak: there is no parameter for the
+ * agent-session id or for the oracle's path, and neither value is reachable
+ * from here. The prompt is free text and the last remaining way to hand the
+ * implementer either one.
+ */
+export function buildStagePrompt(args: {
+  cardId: string;
+  stageId: string;
+  stage: PlaybookStageDef | null;
+}): string {
+  const stageName = args.stage?.name ?? args.stageId;
+  const entryAction = args.stage?.entry_action;
+  return [
+    `## Playbook stage: ${stageName}`,
+    `You are running the "${stageName}" stage for Harmony card ${args.cardId}.`,
+    entryAction
+      ? `Stage skill / entry action: \`${entryAction}\`. Follow that skill's method for this stage.`
+      : "Read the card with the Harmony MCP tools (`harmony_get_card`) and do this stage's work for it.",
+    "Do only this stage's work, then stop. Do not move the card, do not advance the stage, and do not end your agent session — the driver that invoked this stage owns all three.",
+  ].join("\n");
+}
+
+/**
+ * The pinned stage this run is bound to, or a refusal. Two OUTCOMES, kept
+ * apart on purpose:
+ *
+ *  - `ok: true` with `gate: null` — the stage exists and simply declares no
+ *    gate. The run proceeds: the stage's `role` and `entry_action` are still
+ *    in force, and nothing is collected or recorded afterwards.
+ *  - `ok: false` — the PIN itself is unusable (a legacy macro snapshot, or a
+ *    stage id that is not in the pinned version). The caller refuses to run.
+ *
+ * Collapsing those two into one `null`, which is what deriving the stage from
+ * `resolveStageGate` did, made an ungated stage lose both its declared role
+ * (silently falling back to the fail-closed `implementer` treatment) and its
+ * `entry_action` prompt — a degradation invisible at runtime.
+ */
+export type PinnedStageResolution =
+  | { ok: true; stage: PlaybookStageDef; gate: GateSpec | null }
+  | { ok: false; reason: string };
+
+/**
+ * Resolve `stageId` against the PINNED `playbook_versions` snapshot and
+ * normalize that stage's gate. Pure and total — `resolveStageDef` and
+ * `normalizeGateSpec` are both pure, and neither throws.
+ *
+ * A gate whose `kind` is unknown normalizes to `null` (fail-closed in
+ * `normalizeGateSpec`): the stage still runs, and nothing is collected. That
+ * is deliberately NOT a refusal — the stage def is intact, only its gate is
+ * unreadable.
+ */
+export function resolvePinnedStage(
+  version: PlaybookVersionDef,
+  stageId: string,
+): PinnedStageResolution {
+  const resolution = resolveStageDef(version, stageId);
+  if (resolution.kind === "not_stage_model") {
+    return {
+      ok: false,
+      reason: `the pinned playbook version is a legacy macro (steps_version ${version.steps_version}) and declares no stages`,
+    };
+  }
+  if (resolution.kind === "stage_not_found") {
+    return {
+      ok: false,
+      reason: `stage "${stageId}" is not in the pinned playbook version`,
+    };
+  }
+  return {
+    ok: true,
+    stage: resolution.stage,
+    gate: normalizeGateSpec(resolution.stage.gate),
+  };
+}
+
+/** A stage's subagent launch, in the two shapes `SdkAgentRunner` consumes. */
+export interface StageRunnerLaunch {
+  /** The NORMALIZED role (`buildRoleLaunch`), never the raw input. */
+  role: PlaybookStageRole | null;
+  prompt: string;
+  cwd: string;
+  /**
+   * The runner config carrying Task 13's two measures: the scoped `Read` deny
+   * over the credential directory, and the environment keys the child must not
+   * receive. `stripEnvKeys` is DERIVED from the launch's own omissions, so
+   * `HARMONY_CREDENTIAL_KEYS` stays the only credential list in the codebase.
+   */
+  config: SdkRunnerConfig;
+}
+
+/**
+ * Build the subagent launch for one stage: the role's env strip and tool deny,
+ * plus the prompt and worktree the run input needs.
+ *
+ * Both enforcement fields are asserted in `stage-cli.test.ts`, so removing
+ * either one fails a test rather than silently disarming the role separation.
+ */
+export function buildStageRunnerConfig(args: {
+  role: PlaybookStageRole | null;
+  prompt: string;
+  repoPath: string;
+  parentEnv: Record<string, string | undefined>;
+}): StageRunnerLaunch {
+  const launch = buildRoleLaunch(args);
+  return {
+    role: launch.role,
+    prompt: launch.prompt,
+    cwd: launch.repoPath,
+    config: {
+      disallowedTools: launch.disallowedTools,
+      stripEnvKeys: envKeysDroppedByLaunch(args.parentEnv, launch),
+    },
+  };
+}

package/src/stage-run.ts

@@ -0,0 +1,91 @@
+/**
+ * One stage, one invocation. This is the whole orchestration the motor performs:
+ * announce the stage, run the subagent for its role, collect the gate's evidence,
+ * report. It deliberately does NOT decide what runs next and does NOT form a
+ * verdict — Harmony advances the stage, and `gateEvaluate` in @harmony/shared
+ * turns evidence into pass or fail.
+ *
+ * The deps are injected so the orchestration is testable without a repo, a
+ * subagent, or a network. The real wiring lives in cli.ts.
+ */
+import type {
+  GateEvidence,
+  GateSpec,
+  PlaybookStageRole,
+} from "@harmony/shared";
+
+export interface StageRunRequest {
+  cardId: string;
+  stageId: string;
+  workspaceId: string;
+  repoPath: string;
+  /**
+   * The card's ACTIVE agent session id (Task 11 review, ruling 27). The oracle
+   * read route binds the caller to it, so the driver that claimed the stage
+   * threads its own session id in through the CLI's `--session` flag. It is
+   * passed to the oracle deps and to the runner's event labels ONLY — it never
+   * enters the subagent's prompt or context.
+   */
+  sessionId: string;
+  /**
+   * The stage's role (Task 8). The real `runRole` builds its subagent launch
+   * from this via `buildRoleLaunch` (runner.ts). `null` fails closed — treated
+   * like `implementer`, not like an unrestricted default.
+   */
+  role: PlaybookStageRole | null;
+}
+
+export type MotorEvent =
+  | { type: "stage_entered"; stageId: string }
+  | {
+      type: "gate_evaluated";
+      stageId: string;
+      gateKind: string;
+      result: string;
+    };
+
+export interface StageRunDeps {
+  /** Resolve the pinned stage's gate, or null when the stage declares none. */
+  resolveGate(request: StageRunRequest): Promise<GateSpec | null>;
+  /** Run the subagent for this stage's role. Returns when it has exited. */
+  runRole(request: StageRunRequest): Promise<void>;
+  /** Collect the gate's evidence. Called only after runRole has resolved. */
+  collect(request: StageRunRequest, gate: GateSpec): Promise<GateEvidence>;
+}
+
+export interface StageRunResult {
+  stageId: string;
+  gateKind: string | null;
+  evidence: GateEvidence | null;
+  events: MotorEvent[];
+}
+
+export async function runStage(
+  request: StageRunRequest,
+  deps: StageRunDeps,
+): Promise<StageRunResult> {
+  const events: MotorEvent[] = [
+    { type: "stage_entered", stageId: request.stageId },
+  ];
+
+  const gate = await deps.resolveGate(request);
+
+  // The role's subagent always runs to completion BEFORE any gate is collected.
+  // Task 12's oracle collector relies on this ordering: the held test and a model
+  // must never share a filesystem window.
+  await deps.runRole(request);
+
+  if (!gate) {
+    return { stageId: request.stageId, gateKind: null, evidence: null, events };
+  }
+
+  const evidence = await deps.collect(request, gate);
+  events.push({
+    type: "gate_evaluated",
+    stageId: request.stageId,
+    gateKind: gate.kind,
+    result: evidence.result,
+  });
+
+  return { stageId: request.stageId, gateKind: gate.kind, evidence, events };
+}