harnery 0.7.1 → 0.9.0

package/src/core/workflow/types.ts

@@ -0,0 +1,153 @@
+/**
+ * Workflow engine contracts. A workflow is a small throwaway JS script with
+ * bounded, schema-gated stages that fan work out to headless harness-CLI
+ * subagents; the SCRIPT (deterministic code), not any model, decides routing
+ * between stages, and the run always terminates when the script returns.
+ *
+ * Design record: decision 0015 (portable coordination-aware workflows).
+ */
+
+import type { BillingMode, BillingProber } from "./billing.ts";
+
+/** JSON-schema *subset* accepted by stage gates (see validate.ts). */
+export interface StageSchema {
+  type: "object" | "array" | "string" | "number" | "boolean";
+  /** type=object */
+  properties?: Record<string, StageSchema>;
+  required?: string[];
+  /** type=array */
+  items?: StageSchema;
+  /** any type: closed value set (compared with ===) */
+  enum?: Array<string | number | boolean>;
+}
+
+export interface AgentOpts {
+  /** Stage gate: when present, the agent's reply must strict-parse as JSON and
+   * validate; the engine retries with the validation error appended, up to
+   * `maxAttempts`. Without it, `agent()` resolves to the raw reply text. */
+  schema?: StageSchema;
+  /** Model slug passed through to the harness CLI (default: the CLI's default). */
+  model?: string;
+  /** Attempt ceiling for the schema-retry loop (default 2). */
+  maxAttempts?: number;
+  /** Subprocess timeout ms (default 300_000). */
+  timeoutMs?: number;
+  /** Harness-turn ceiling for the child (default 25; use 1 for pure
+   * classification stages — cheaper and faster). */
+  maxTurns?: number;
+  /** Display label in the journal (default: prompt head). */
+  label?: string;
+  /** Which harness runs this agent (default: the run's default harness).
+   * Mixed-harness workflows are legal: triage on one CLI, deep work on
+   * another. */
+  harness?: HarnessName;
+}
+
+export type HarnessName = "claude-code" | "codex" | "cursor";
+
+/** What a spawn adapter returns for one subagent run. */
+export interface SpawnResult {
+  ok: boolean;
+  /** The model's final reply text (envelope-unwrapped). */
+  text: string;
+  /** Child harness session id when the envelope carries one. */
+  sessionId?: string;
+  costUsd?: number;
+  durationMs: number;
+  /** Populated when ok=false. */
+  error?: string;
+}
+
+export interface SpawnRequest {
+  prompt: string;
+  model?: string;
+  timeoutMs: number;
+  maxTurns: number;
+  cwd: string;
+  /** Run id, stamped into the child env (HARNERY_WORKFLOW_RUN_ID) so the
+   * coord layer can associate child sessions with their workflow run. */
+  runId?: string;
+  /** Scrub all API-key vars from the child env so it can only authenticate
+   * via its stored (subscription) login. See billing.ts. */
+  subscriptionOnly?: boolean;
+}
+
+/** One headless-subagent runner. The engine is adapter-agnostic; claude-code
+ * ships first, codex/cursor land behind the same signature (plan Phase 4). */
+export type Spawner = (req: SpawnRequest) => Promise<SpawnResult>;
+
+/** The API surface injected into a workflow script's default export. Explicit
+ * injection (no ambient globals): keeps scripts portable and unit-testable. */
+export interface WorkflowContext {
+  /** Spawn one subagent; resolves to validated JSON (schema) or reply text. */
+  agent: (prompt: string, opts?: AgentOpts) => Promise<unknown>;
+  /** Run thunks with bounded concurrency; a rejected thunk resolves to null. */
+  parallel: <T>(thunks: Array<() => Promise<T>>) => Promise<Array<T | null>>;
+  /** Declare the current stage (journal + progress grouping). */
+  stage: (title: string) => void;
+  /** Narrate progress (stderr + journal). */
+  log: (message: string) => void;
+}
+
+export interface WorkflowMeta {
+  name: string;
+  description?: string;
+}
+
+/** Loaded script shape: `export const meta` + `export default async (ctx) => …`. */
+export interface WorkflowModule {
+  meta?: WorkflowMeta;
+  default: (ctx: WorkflowContext) => Promise<unknown>;
+}
+
+export interface EngineOpts {
+  /** Repo root whose .harnery/ receives the run journal. */
+  coordRoot: string;
+  /** Spawner registry keyed by harness. A single-harness caller registers one
+   * entry and names it in `defaultHarness`. */
+  spawners: Partial<Record<HarnessName, Spawner>>;
+  /** Harness used when an agent() call doesn't name one (default "claude-code"). */
+  defaultHarness?: HarnessName;
+  /** Resume: run id of a prior run whose journal supplies cached results.
+   * agent() calls whose (stage, prompt, model, maxTurns, schema) key matches a
+   * completed prior agent return the journaled result without spawning. */
+  resumeFrom?: string;
+  /** Total-agent ceiling for the run (default 50): the runaway backstop. */
+  maxAgents?: number;
+  /** Concurrent-subagent cap for parallel() (default 4). */
+  concurrency?: number;
+  /** Working directory children spawn in (default: coordRoot). */
+  cwd?: string;
+  /** Progress sink (default: process.stderr). */
+  onLog?: (line: string) => void;
+  /** Guarantee subscription billing: API-key vars are scrubbed from every
+   * child env, and a harness whose stored login is provably absent fails
+   * loud before spawning. */
+  subscriptionOnly?: boolean;
+  /** Permit the api-key-override billing state (an exported API key silently
+   * shadowing a stored subscription login), which the engine otherwise
+   * refuses. Deliberate key-only hosts don't need this — only the
+   * both-present case does. */
+  allowApiBilling?: boolean;
+  /** Billing-probe override for tests (default: the real probeBilling). */
+  probeBilling?: BillingProber;
+}
+
+export interface RunReport {
+  runId: string;
+  name: string;
+  /** What the script's default export returned. */
+  result: unknown;
+  agentsSpawned: number;
+  /** agent() calls satisfied from the resumeFrom journal without spawning. */
+  agentsCached: number;
+  costUsd: number;
+  durationMs: number;
+  journalPath: string;
+  /** Estimated tokens of repo instructions (CLAUDE.md/AGENTS.md at the child
+   * cwd) that EVERY child cache-writes on spawn — the fixed per-child context
+   * overhead a fan-out multiplies. bytes/4 heuristic; 0 when no such file. */
+  contextTokensPerChildEstimate: number;
+  /** Billing mode per harness actually used this run (probed on first use). */
+  billing: Array<{ harness: HarnessName; mode: BillingMode }>;
+}

package/src/core/workflow/validate.ts

@@ -0,0 +1,75 @@
+/**
+ * Minimal validator for the StageSchema JSON-schema subset. Deliberately tiny:
+ * a full JSON Schema implementation would pull a dependency (ajv) for
+ * validation depth workflow gates don't need. Supported: type, properties,
+ * required, items, enum. Returns a list of human-readable problems (empty =
+ * valid) so the engine can feed failures back into the retry prompt verbatim.
+ */
+
+import type { StageSchema } from "./types.ts";
+
+export function validateAgainstSchema(value: unknown, schema: StageSchema, path = "$"): string[] {
+  const problems: string[] = [];
+
+  if (schema.enum) {
+    if (!schema.enum.some((v) => v === value)) {
+      problems.push(`${path}: expected one of ${JSON.stringify(schema.enum)}, got ${short(value)}`);
+    }
+    return problems; // enum is exhaustive; type check is implied by membership
+  }
+
+  switch (schema.type) {
+    case "object": {
+      if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return [`${path}: expected object, got ${short(value)}`];
+      }
+      const obj = value as Record<string, unknown>;
+      for (const key of schema.required ?? []) {
+        if (!(key in obj)) problems.push(`${path}.${key}: required property missing`);
+      }
+      for (const [key, sub] of Object.entries(schema.properties ?? {})) {
+        if (key in obj) problems.push(...validateAgainstSchema(obj[key], sub, `${path}.${key}`));
+      }
+      return problems;
+    }
+    case "array": {
+      if (!Array.isArray(value)) return [`${path}: expected array, got ${short(value)}`];
+      if (schema.items) {
+        for (const [i, item] of value.entries()) {
+          problems.push(
+            ...validateAgainstSchema(item, schema.items as StageSchema, `${path}[${i}]`),
+          );
+        }
+      }
+      return problems;
+    }
+    case "string":
+    case "number":
+    case "boolean": {
+      if (typeof value !== schema.type) {
+        problems.push(`${path}: expected ${schema.type}, got ${short(value)}`);
+      }
+      return problems;
+    }
+    default:
+      return [`${path}: unsupported schema type ${String((schema as { type?: unknown }).type)}`];
+  }
+}
+
+/** Strip accidental markdown code fences, then strict-parse JSON. */
+export function parseStageOutput(text: string): { value?: unknown; error?: string } {
+  const stripped = text
+    .trim()
+    .replace(/^```(?:json)?\s*/i, "")
+    .replace(/\s*```$/, "");
+  try {
+    return { value: JSON.parse(stripped) };
+  } catch (err) {
+    return { error: `not valid JSON: ${(err as Error).message}` };
+  }
+}
+
+function short(value: unknown): string {
+  const s = JSON.stringify(value);
+  return s === undefined ? String(value) : s.length > 60 ? `${s.slice(0, 60)}…` : s;
+}

package/src/lib/tools/ripgrep.ts

@@ -0,0 +1,244 @@
+import { spawn, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { readFile, stat } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { resolveBinName, ripgrepAutoInstall } from "../../core/config.ts";
+import { coordEnv } from "../env.ts";
+
+/**
+ * Managed ripgrep provisioning for `grep --files` / content search.
+ *
+ * harnery can install a pinned, checksum-verified ripgrep into its own tools
+ * directory (`$XDG_DATA_HOME/harnery/tools`, default `~/.local/share/harnery/
+ * tools`) so `harn grep` gets the fast engine even on machines where nobody
+ * ever installed rg. The download is version-pinned and every artifact's
+ * sha256 is baked in below (cross-checked against the official release
+ * checksums), so the install is reproducible, never "whatever is latest."
+ *
+ * Consent model: the installer only runs automatically when the host project
+ * opts in via `.harnery/config.jsonc` `{ "tools": { "ripgrep": { "autoInstall":
+ * true } } }` — a repo commits that once and every clone self-heals. Without
+ * the opt-in, a missing rg produces a rate-limited stderr hint naming
+ * `harn doctor --fix` (explicit install). Environments that forbid downloads
+ * lose nothing: every failure path falls back to GNU grep.
+ */
+
+export const RG_VERSION = "14.1.1";
+
+/** sha256 pins verified against the official ripgrep release .sha256 assets. */
+const ARTIFACTS: Record<string, { name: string; sha256: string }> = {
+  "linux-x64": {
+    name: `ripgrep-${RG_VERSION}-x86_64-unknown-linux-musl.tar.gz`,
+    sha256: "4cf9f2741e6c465ffdb7c26f38056a59e2a2544b51f7cc128ef28337eeae4d8e",
+  },
+  "linux-arm64": {
+    name: `ripgrep-${RG_VERSION}-aarch64-unknown-linux-gnu.tar.gz`,
+    sha256: "c827481c4ff4ea10c9dc7a4022c8de5db34a5737cb74484d62eb94a95841ab2f",
+  },
+  "darwin-x64": {
+    name: `ripgrep-${RG_VERSION}-x86_64-apple-darwin.tar.gz`,
+    sha256: "fc87e78f7cb3fea12d69072e7ef3b21509754717b746368fd40d88963630e2b3",
+  },
+  "darwin-arm64": {
+    name: `ripgrep-${RG_VERSION}-aarch64-apple-darwin.tar.gz`,
+    sha256: "24ad76777745fbff131c8fbc466742b011f925bfa4fffa2ded6def23b5b937be",
+  },
+};
+
+function platformKey(): string {
+  return `${process.platform}-${process.arch}`;
+}
+
+/** True when a pinned artifact exists for this OS/arch (Windows: not yet). */
+export function rgInstallSupported(): boolean {
+  return platformKey() in ARTIFACTS;
+}
+
+/** Machine-level harnery tools dir (NOT the per-project .harnery/ state dir). */
+export function toolsDir(): string {
+  const xdg = process.env.XDG_DATA_HOME;
+  const base = xdg && xdg.trim() !== "" ? xdg : join(homedir(), ".local", "share");
+  return join(base, "harnery", "tools");
+}
+
+/** Path the managed rg binary lives at once installed. */
+export function managedRgPath(): string {
+  return join(toolsDir(), "rg");
+}
+
+function isExecutable(p: string): boolean {
+  try {
+    const r = spawnSync(p, ["--version"], { stdio: "ignore" });
+    return r.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Locate a usable ripgrep. Precedence:
+ *   1. HARNERY_RG_PATH (explicit override)
+ *   2. the managed tools-dir install (works even when PATH doesn't carry it)
+ *   3. `rg` on PATH
+ * Returns the spawnable path/name, or null when none respond to --version.
+ */
+export function findRg(): string | null {
+  const override = coordEnv("RG_PATH");
+  if (override && override.trim() !== "") {
+    return isExecutable(override) ? override : null;
+  }
+  const managed = managedRgPath();
+  if (existsSync(managed) && isExecutable(managed)) return managed;
+  if (isExecutable("rg")) return "rg";
+  return null;
+}
+
+/**
+ * Download + verify + install the pinned ripgrep into the tools dir.
+ * Atomic: extracts to a temp dir and renames the binary into place.
+ * Throws on unsupported platform, network failure, or checksum mismatch —
+ * callers are expected to fall back to grep and say why.
+ */
+export async function installRg(log?: (line: string) => void): Promise<string> {
+  const key = platformKey();
+  const artifact = ARTIFACTS[key];
+  if (!artifact) {
+    throw new Error(
+      `no pinned ripgrep artifact for ${key} — install ripgrep manually (https://github.com/BurntSushi/ripgrep#installation)`,
+    );
+  }
+
+  const url = `https://github.com/BurntSushi/ripgrep/releases/download/${RG_VERSION}/${artifact.name}`;
+  log?.(`downloading ${artifact.name} (pinned ${RG_VERSION})...`);
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`download failed: HTTP ${res.status} for ${url}`);
+  const bytes = Buffer.from(await res.arrayBuffer());
+
+  const digest = createHash("sha256").update(bytes).digest("hex");
+  if (digest !== artifact.sha256) {
+    throw new Error(
+      `sha256 mismatch for ${artifact.name}: expected ${artifact.sha256}, got ${digest} — refusing to install`,
+    );
+  }
+
+  const work = join(tmpdir(), `harnery-rg-${process.pid}`);
+  rmSync(work, { recursive: true, force: true });
+  mkdirSync(work, { recursive: true });
+  try {
+    const tarball = join(work, artifact.name);
+    writeFileSync(tarball, bytes);
+    await extractTar(tarball, work);
+
+    const extractedRg = join(work, artifact.name.replace(/\.tar\.gz$/, ""), "rg");
+    const rgStat = await stat(extractedRg);
+    if (!rgStat.isFile()) throw new Error(`extracted archive missing rg binary at ${extractedRg}`);
+
+    mkdirSync(toolsDir(), { recursive: true });
+    const dest = managedRgPath();
+    // rename() can't cross filesystems (tmp is often tmpfs); copy + rename
+    // within the destination dir keeps the final placement atomic.
+    const staged = `${dest}.tmp-${process.pid}`;
+    writeFileSync(staged, await readFile(extractedRg));
+    chmodSync(staged, 0o755);
+    renameSync(staged, dest);
+
+    if (!isExecutable(dest)) {
+      rmSync(dest, { force: true });
+      throw new Error(`installed rg at ${dest} but it failed to execute`);
+    }
+    log?.(`installed ripgrep ${RG_VERSION} -> ${dest}`);
+    return dest;
+  } finally {
+    rmSync(work, { recursive: true, force: true });
+  }
+}
+
+function extractTar(tarball: string, cwd: string): Promise<void> {
+  return new Promise((resolveP, reject) => {
+    const proc = spawn("tar", ["xzf", tarball], { cwd, stdio: ["ignore", "ignore", "pipe"] });
+    let stderr = "";
+    proc.stderr.setEncoding("utf8");
+    proc.stderr.on("data", (c: string) => {
+      stderr += c;
+    });
+    proc.on("error", reject);
+    proc.on("close", (code) => {
+      if (code === 0) resolveP();
+      else reject(new Error(`tar exited ${code}: ${stderr.trim()}`));
+    });
+  });
+}
+
+export type SearchEngine = "rg" | "grep";
+
+/**
+ * Shared engine resolver for the ripgrep-backed search commands (`grep`,
+ * `callers`). Returns the engine plus the spawnable rg path.
+ *
+ * `HARNERY_GREP_ENGINE=rg|grep` forces one; otherwise findRg() probes
+ * HARNERY_RG_PATH → the managed tools-dir install → PATH. On a miss, the
+ * host's `.harnery/config.jsonc` `tools.ripgrep.autoInstall` consent triggers
+ * a pinned, checksum-verified install into the harnery tools dir (any failure
+ * falls back to grep with a stderr note); without consent, a rate-limited
+ * stderr hint (keyed per `hintKey`) names the explicit install command.
+ */
+export async function resolveSearchEngine(
+  hintKey = "grep",
+): Promise<{ engine: SearchEngine; rgBin: string }> {
+  const forced = coordEnv("GREP_ENGINE");
+  if (forced === "grep") return { engine: "grep", rgBin: "rg" };
+  const found = findRg();
+  if (found) return { engine: "rg", rgBin: found };
+  if (forced === "rg") {
+    // Forced rg with none findable: let the spawn error surface loudly.
+    return { engine: "rg", rgBin: "rg" };
+  }
+  if (rgInstallSupported()) {
+    if (ripgrepAutoInstall()) {
+      try {
+        const installed = await installRg((line) => process.stderr.write(`harnery: ${line}\n`));
+        return { engine: "rg", rgBin: installed };
+      } catch (err) {
+        process.stderr.write(
+          `harnery: ripgrep auto-install failed (${(err as Error).message}); using grep fallback\n`,
+        );
+        return { engine: "grep", rgBin: "rg" };
+      }
+    }
+    const bin = resolveBinName();
+    hintOncePerDay(
+      `${bin} ${hintKey}: ripgrep not found; using the slower GNU grep fallback. ` +
+        `Run \`${bin} doctor --fix\` to install it (pinned + checksum-verified), ` +
+        `or set { "tools": { "ripgrep": { "autoInstall": true } } } in .harnery/config.jsonc.`,
+    );
+  }
+  return { engine: "grep", rgBin: "rg" };
+}
+
+/**
+ * Emit `line` to stderr at most once per 24h (stamp file in the tools dir).
+ * Keeps the "rg missing" nudge from nagging on every single grep invocation.
+ */
+export function hintOncePerDay(line: string): void {
+  try {
+    const stamp = join(toolsDir(), ".rg-hint-stamp");
+    if (existsSync(stamp) && Date.now() - statSync(stamp).mtimeMs < 24 * 60 * 60 * 1000) {
+      return;
+    }
+    mkdirSync(toolsDir(), { recursive: true });
+    writeFileSync(stamp, String(Date.now()));
+  } catch {
+    // stamping failed; still emit the hint
+  }
+  process.stderr.write(`${line}\n`);
+}