harnery 0.9.0 → 0.10.0

package/src/core/workflow/spawn-claude.ts

@@ -19,6 +19,8 @@
  */
 
 import { exec } from "../../lib/exec.ts";
+import { validateHarnessEffort } from "../harnesses/profiles.ts";
+import type { HarnessInvocation, HarnessRawResult } from "../harnesses/types.ts";
 import { buildChildEnv } from "./child-env.ts";
 import { notFoundError } from "./harnesses.ts";
 import type { Spawner, SpawnRequest, SpawnResult } from "./types.ts";
@@ -33,9 +35,8 @@ interface ClaudeEnvelope {
   errors?: string[];
 }
 
-export const claudeCodeSpawner: Spawner = async (req: SpawnRequest): Promise<SpawnResult> => {
-  const t0 = Date.now();
-
+export function buildClaudeInvocation(req: SpawnRequest): HarnessInvocation {
+  validateHarnessEffort("claude-code", req.effort);
   const argv = [
     "claude",
     "-p",
@@ -46,35 +47,37 @@ export const claudeCodeSpawner: Spawner = async (req: SpawnRequest): Promise<Spa
     String(req.maxTurns),
   ];
   if (req.model) argv.push("--model", req.model);
+  if (req.effort) argv.push("--effort", req.effort);
+  return { argv };
+}
 
-  const r = await exec(argv, {
-    cwd: req.cwd,
-    env: buildChildEnv(req.runId, { subscriptionOnly: req.subscriptionOnly }),
-    timeout: req.timeoutMs,
-  });
-  const durationMs = Date.now() - t0;
-
-  if (r.exitCode === 127) {
-    return { ok: false, text: "", durationMs, error: notFoundError("claude-code") };
+export function normalizeClaudeResult(raw: HarnessRawResult): SpawnResult {
+  if (raw.exitCode === 127) {
+    return {
+      ok: false,
+      text: "",
+      durationMs: raw.durationMs,
+      error: notFoundError("claude-code"),
+    };
   }
-  if (r.exitCode !== 0) {
+  if (raw.exitCode !== 0) {
     return {
       ok: false,
       text: "",
-      durationMs,
-      error: `claude exited ${r.exitCode}: ${(r.stderr || r.stdout).slice(0, 500)}`,
+      durationMs: raw.durationMs,
+      error: `claude exited ${raw.exitCode}: ${(raw.stderr || raw.stdout).slice(0, 500)}`,
     };
   }
 
   let envelope: ClaudeEnvelope;
   try {
-    envelope = JSON.parse(r.stdout) as ClaudeEnvelope;
+    envelope = JSON.parse(raw.stdout) as ClaudeEnvelope;
   } catch {
     return {
       ok: false,
       text: "",
-      durationMs,
-      error: `result envelope was not JSON: ${r.stdout.slice(0, 300)}`,
+      durationMs: raw.durationMs,
+      error: `result envelope was not JSON: ${raw.stdout.slice(0, 300)}`,
     };
   }
 
@@ -84,7 +87,7 @@ export const claudeCodeSpawner: Spawner = async (req: SpawnRequest): Promise<Spa
       text: String(envelope.result ?? ""),
       sessionId: envelope.session_id,
       costUsd: envelope.total_cost_usd,
-      durationMs,
+      durationMs: raw.durationMs,
       error: `harness error (${envelope.subtype ?? "unknown"}): ${(envelope.errors ?? []).join("; ") || "see envelope"}`,
     };
   }
@@ -94,6 +97,22 @@ export const claudeCodeSpawner: Spawner = async (req: SpawnRequest): Promise<Spa
     text: String(envelope.result ?? ""),
     sessionId: envelope.session_id,
     costUsd: envelope.total_cost_usd,
-    durationMs,
+    durationMs: raw.durationMs,
   };
+}
+
+export const claudeCodeSpawner: Spawner = async (req: SpawnRequest): Promise<SpawnResult> => {
+  const t0 = Date.now();
+  let invocation: HarnessInvocation;
+  try {
+    invocation = buildClaudeInvocation(req);
+  } catch (error) {
+    return { ok: false, text: "", durationMs: 0, error: (error as Error).message };
+  }
+  const r = await exec(invocation.argv, {
+    cwd: req.cwd,
+    env: buildChildEnv(req.runId, { subscriptionOnly: req.subscriptionOnly }),
+    timeout: req.timeoutMs,
+  });
+  return normalizeClaudeResult({ ...r, durationMs: Date.now() - t0 });
 };

package/src/core/workflow/spawn-codex.ts

@@ -20,54 +20,73 @@ import { existsSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { exec } from "../../lib/exec.ts";
+import { validateHarnessEffort } from "../harnesses/profiles.ts";
+import type { HarnessInvocation, HarnessRawResult } from "../harnesses/types.ts";
 import { buildChildEnv } from "./child-env.ts";
 import { notFoundError } from "./harnesses.ts";
 import type { Spawner, SpawnRequest, SpawnResult } from "./types.ts";
 
-export const codexSpawner: Spawner = async (req: SpawnRequest): Promise<SpawnResult> => {
-  const t0 = Date.now();
-  const outFile = join(
-    tmpdir(),
-    `harnery-codex-${process.pid}-${randomBytes(4).toString("hex")}.txt`,
-  );
-
+export function buildCodexInvocation(req: SpawnRequest, resultFile?: string): HarnessInvocation {
+  validateHarnessEffort("codex", req.effort);
+  if (!resultFile) throw new Error("codex adapter requires a final-message result file");
   const argv = [
     "codex",
     "exec",
     req.prompt,
     "--output-last-message",
-    outFile,
+    resultFile,
     "--skip-git-repo-check",
     "--sandbox",
     "workspace-write",
   ];
   if (req.model) argv.push("--model", req.model);
+  if (req.effort) argv.push("-c", `model_reasoning_effort=${JSON.stringify(req.effort)}`);
+  return { argv, resultFile };
+}
+
+export function normalizeCodexResult(raw: HarnessRawResult): SpawnResult {
+  if (raw.exitCode === 127) {
+    return { ok: false, text: "", durationMs: raw.durationMs, error: notFoundError("codex") };
+  }
+  if (raw.exitCode !== 0) {
+    return {
+      ok: false,
+      text: "",
+      durationMs: raw.durationMs,
+      error: `codex exited ${raw.exitCode}: ${(raw.stderr || raw.stdout).slice(0, 500)}`,
+    };
+  }
+  return {
+    ok: true,
+    text: (raw.resultFileText ?? raw.stdout).trim(),
+    durationMs: raw.durationMs,
+  };
+}
+
+export const codexSpawner: Spawner = async (req: SpawnRequest): Promise<SpawnResult> => {
+  const t0 = Date.now();
+  const outFile = join(
+    tmpdir(),
+    `harnery-codex-${process.pid}-${randomBytes(4).toString("hex")}.txt`,
+  );
 
   try {
-    const r = await exec(argv, {
+    let invocation: HarnessInvocation;
+    try {
+      invocation = buildCodexInvocation(req, outFile);
+    } catch (error) {
+      return { ok: false, text: "", durationMs: 0, error: (error as Error).message };
+    }
+    const r = await exec(invocation.argv, {
       cwd: req.cwd,
       env: buildChildEnv(req.runId, { subscriptionOnly: req.subscriptionOnly }),
       timeout: req.timeoutMs,
     });
-    const durationMs = Date.now() - t0;
-
-    if (r.exitCode === 127) {
-      return { ok: false, text: "", durationMs, error: notFoundError("codex") };
-    }
-    if (r.exitCode !== 0) {
-      return {
-        ok: false,
-        text: "",
-        durationMs,
-        error: `codex exited ${r.exitCode}: ${(r.stderr || r.stdout).slice(0, 500)}`,
-      };
-    }
-
-    if (!existsSync(outFile)) {
-      // Exit 0 but no last-message file: fall back to stdout (contract drift guard).
-      return { ok: true, text: r.stdout, durationMs };
-    }
-    return { ok: true, text: readFileSync(outFile, "utf8").trim(), durationMs };
+    return normalizeCodexResult({
+      ...r,
+      durationMs: Date.now() - t0,
+      resultFileText: existsSync(outFile) ? readFileSync(outFile, "utf8") : undefined,
+    });
   } finally {
     rmSync(outFile, { force: true });
   }

package/src/core/workflow/spawn-cursor.ts

@@ -17,6 +17,8 @@
  */
 
 import { exec } from "../../lib/exec.ts";
+import { validateHarnessEffort } from "../harnesses/profiles.ts";
+import type { HarnessInvocation, HarnessRawResult } from "../harnesses/types.ts";
 import { buildChildEnv } from "./child-env.ts";
 import { notFoundError } from "./harnesses.ts";
 import type { Spawner, SpawnRequest, SpawnResult } from "./types.ts";
@@ -46,44 +48,61 @@ export function parseCursorOutput(stdout: string): {
   }
 }
 
-export const cursorSpawner: Spawner = async (req: SpawnRequest): Promise<SpawnResult> => {
-  const t0 = Date.now();
-
+export function buildCursorInvocation(req: SpawnRequest): HarnessInvocation {
+  validateHarnessEffort("cursor", req.effort);
   // --trust: headless cursor-agent refuses untrusted workspaces (exit 1,
   // "Workspace Trust Required"). Workflow children run in the engine's cwd
   // deliberately and may edit files — the same posture as the codex adapter's
   // `--sandbox workspace-write` — so trusting that directory is implied.
   const argv = ["cursor-agent", "-p", req.prompt, "--output-format", "json", "--trust"];
   if (req.model) argv.push("--model", req.model);
+  return { argv };
+}
 
-  const r = await exec(argv, {
-    cwd: req.cwd,
-    env: buildChildEnv(req.runId, { subscriptionOnly: req.subscriptionOnly }),
-    timeout: req.timeoutMs,
-  });
-  const durationMs = Date.now() - t0;
-
-  if (r.exitCode === 127) {
-    return { ok: false, text: "", durationMs, error: notFoundError("cursor") };
+export function normalizeCursorResult(raw: HarnessRawResult): SpawnResult {
+  if (raw.exitCode === 127) {
+    return { ok: false, text: "", durationMs: raw.durationMs, error: notFoundError("cursor") };
   }
-  if (r.exitCode !== 0) {
+  if (raw.exitCode !== 0) {
     return {
       ok: false,
       text: "",
-      durationMs,
-      error: `cursor-agent exited ${r.exitCode}: ${(r.stderr || r.stdout).slice(0, 500)}`,
+      durationMs: raw.durationMs,
+      error: `cursor-agent exited ${raw.exitCode}: ${(raw.stderr || raw.stdout).slice(0, 500)}`,
     };
   }
 
-  const parsed = parseCursorOutput(r.stdout);
+  const parsed = parseCursorOutput(raw.stdout);
   if (parsed.isError) {
     return {
       ok: false,
       text: parsed.text,
       sessionId: parsed.sessionId,
-      durationMs,
+      durationMs: raw.durationMs,
       error: `cursor-agent reported is_error: ${parsed.text.slice(0, 300)}`,
     };
   }
-  return { ok: true, text: parsed.text, sessionId: parsed.sessionId, durationMs };
+  return {
+    ok: true,
+    text: parsed.text,
+    sessionId: parsed.sessionId,
+    durationMs: raw.durationMs,
+  };
+}
+
+export const cursorSpawner: Spawner = async (req: SpawnRequest): Promise<SpawnResult> => {
+  const t0 = Date.now();
+  let invocation: HarnessInvocation;
+  try {
+    invocation = buildCursorInvocation(req);
+  } catch (error) {
+    return { ok: false, text: "", durationMs: 0, error: (error as Error).message };
+  }
+
+  const r = await exec(invocation.argv, {
+    cwd: req.cwd,
+    env: buildChildEnv(req.runId, { subscriptionOnly: req.subscriptionOnly }),
+    timeout: req.timeoutMs,
+  });
+  return normalizeCursorResult({ ...r, durationMs: Date.now() - t0 });
 };

package/src/core/workflow/types.ts

@@ -28,6 +28,9 @@ export interface AgentOpts {
   schema?: StageSchema;
   /** Model slug passed through to the harness CLI (default: the CLI's default). */
   model?: string;
+  /** Reasoning effort mapped through the selected harness profile. Unsupported
+   * values fail before the vendor process starts. */
+  effort?: string;
   /** Attempt ceiling for the schema-retry loop (default 2). */
   maxAttempts?: number;
   /** Subprocess timeout ms (default 300_000). */
@@ -43,7 +46,10 @@ export interface AgentOpts {
   harness?: HarnessName;
 }
 
-export type HarnessName = "claude-code" | "codex" | "cursor";
+/** Open registry key. The built-in catalog currently contains Claude Code,
+ * Codex, and Cursor; consumers may register another adapter without widening
+ * a package-owned union first. */
+export type HarnessName = string;
 
 /** What a spawn adapter returns for one subagent run. */
 export interface SpawnResult {
@@ -61,6 +67,7 @@ export interface SpawnResult {
 export interface SpawnRequest {
   prompt: string;
   model?: string;
+  effort?: string;
   timeoutMs: number;
   maxTurns: number;
   cwd: string;
@@ -105,7 +112,7 @@ export interface EngineOpts {
   coordRoot: string;
   /** Spawner registry keyed by harness. A single-harness caller registers one
    * entry and names it in `defaultHarness`. */
-  spawners: Partial<Record<HarnessName, Spawner>>;
+  spawners: Readonly<Record<HarnessName, Spawner | undefined>>;
   /** 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.

package/src/lib/browser/client.ts

@@ -74,6 +74,14 @@ export interface BrowserOptions {
    * via this callback (e.g., a Cloudflare-bypass header for specific zones).
    */
   extraHeaders?: (url: string) => Record<string, string>;
+  /**
+   * Extra Chromium command-line flags, passed through to Playwright's
+   * `launchPersistentContext` `args`. Used for environment-specific
+   * workarounds — most notably `--disable-gpu` for headed windows under
+   * WSLg (see `./launch-args.ts`). Empty/undefined means Playwright's
+   * defaults only.
+   */
+  launchArgs?: string[];
 }
 
 export interface NavigateResult {
@@ -98,6 +106,14 @@ export interface FailedRequest {
   method: string;
   failure: string;
   resourceType: string;
+  /** HTTP status for kind "http" entries; null for network-level failures. */
+  status: number | null;
+  /** "http" = request completed with a >=400 response; "network" = never completed (DNS, TLS, aborts, tunnel). */
+  kind: "http" | "network";
+  /** True when the entry is the main frame's document response — lets consumers
+   *  distinguish an expected error-page status (a 404 route under test) from a
+   *  broken subresource. */
+  document?: boolean;
 }
 
 export interface Diagnostics {
@@ -137,6 +153,9 @@ export class Browser {
     this.context = await chromium.launchPersistentContext(this.profileDir, {
       headless: !this.opts.headed,
       viewport: this.opts.viewport ?? { width: 1280, height: 800 },
+      ...(this.opts.launchArgs && this.opts.launchArgs.length > 0
+        ? { args: this.opts.launchArgs }
+        : {}),
       ...(this.opts.recordHarPath
         ? { recordHar: { path: this.opts.recordHarPath, mode: "full" as const } }
         : {}),
@@ -192,6 +211,24 @@ export class Browser {
         method: req.method(),
         failure: req.failure()?.errorText ?? "unknown",
         resourceType: req.resourceType(),
+        status: null,
+        kind: "network",
+      });
+    });
+    // HTTP-level failures: `requestfailed` only fires for requests that never
+    // complete (DNS, TLS, aborts), so a script/stylesheet answered with a
+    // 4xx/5xx would otherwise be invisible to failedRequests-based gates.
+    page.on("response", (res) => {
+      if (res.status() < 400) return;
+      const req = res.request();
+      this.failedRequests.push({
+        url: res.url(),
+        method: req.method(),
+        failure: `HTTP ${res.status()}`,
+        resourceType: req.resourceType(),
+        status: res.status(),
+        kind: "http",
+        document: req.resourceType() === "document" && res.frame() === page.mainFrame(),
       });
     });
   }

package/src/lib/browser/index.ts

@@ -12,6 +12,7 @@ export {
   type DevOverlayError,
   type DevOverlayResult,
 } from "./dev-overlay.js";
+export { isWSL, wslHeadedLaunchArgs } from "./launch-args.js";
 export type {
   OverflowElement,
   OverflowResult,

package/src/lib/browser/launch-args.ts

@@ -0,0 +1,33 @@
+import { readFileSync } from "node:fs";
+
+/**
+ * Chromium launch-arg helpers for environment-specific workarounds.
+ *
+ * The one that matters today is WSLg: a headed Chromium window renders its
+ * page to a GPU-backed surface that WSLg composites over an RDP stream to the
+ * Windows host. On a range of Windows / GPU-driver / WSLg combinations that
+ * GPU-composited surface never presents, so the window shows in the taskbar
+ * but paints blank — even though the page itself runs fine (JS, navigation,
+ * and DOM all work). Forcing Chromium onto its software compositor with
+ * `--disable-gpu` restores on-screen paint. It only matters for headed mode
+ * (headless never composites to a display) and only under WSL.
+ */
+
+/** True when running under WSL (WSL1 or WSL2). */
+export function isWSL(): boolean {
+  if (process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP) return true;
+  try {
+    return /microsoft|wsl/i.test(readFileSync("/proc/version", "utf8"));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Chromium launch flags to make a headed window paint under WSLg. Returns
+ * `["--disable-gpu"]` on WSL, `[]` elsewhere. Callers apply these only for
+ * headed launches. See the module doc for the failure mode.
+ */
+export function wslHeadedLaunchArgs(): string[] {
+  return isWSL() ? ["--disable-gpu"] : [];
+}