harnery 0.9.0 → 0.11.0

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

@@ -9,6 +9,164 @@
 
 import type { BillingMode, BillingProber } from "./billing.ts";
 
+export const WORKFLOW_PROOF_SCHEMA_VERSION = 1 as const;
+
+export type EvidenceKind = "test" | "command" | "artifact" | "change" | "review" | "observation";
+export type EvidenceStatus = "passed" | "failed" | "observed" | "unknown";
+export type EvidenceSource = "workflow" | "engine";
+export type AcceptanceStatus = "satisfied" | "unsatisfied" | "unknown";
+export type WorkflowRunStatus = "succeeded" | "failed";
+
+export interface AcceptanceCriterion {
+  /** Stable identifier referenced by evidence, for example `tests-pass`. */
+  id: string;
+  statement: string;
+}
+
+export interface WorkflowEvidenceInput {
+  kind: EvidenceKind;
+  status: EvidenceStatus;
+  label: string;
+  summary?: string;
+  /** Inspectable local path, URL, command name, or other bounded reference. */
+  ref?: string;
+  /** Declared acceptance criteria this evidence bears on. */
+  acceptanceIds?: string[];
+}
+
+export interface WorkflowEvidenceRecord {
+  id: string;
+  source: EvidenceSource;
+  recorded_at: string;
+  kind: EvidenceKind;
+  status: EvidenceStatus;
+  label: string;
+  summary?: string;
+  ref?: string;
+  stage?: string;
+  acceptance_ids: string[];
+}
+
+export interface AcceptanceResult extends AcceptanceCriterion {
+  status: AcceptanceStatus;
+  evidence_ids: string[];
+  /** Sources behind the decisive evidence. Empty when status is unknown. */
+  sources: EvidenceSource[];
+}
+
+export interface AcceptanceSummary {
+  satisfied: number;
+  unsatisfied: number;
+  unknown: number;
+  total: number;
+}
+
+export interface ResultDigest {
+  kind: "text" | "json";
+  sha256: string;
+  bytes: number;
+}
+
+export interface WorkflowAgentProof {
+  id: string;
+  label: string;
+  stage?: string;
+  harness: HarnessName;
+  model?: string;
+  status: "succeeded" | "failed" | "cached";
+  attempts: number;
+  duration_ms: number;
+  cost_usd?: number;
+  session_id?: string;
+  result?: ResultDigest;
+  error?: string;
+}
+
+export interface WorkflowRepoSnapshot {
+  cwd: string;
+  root?: string;
+  branch?: string;
+  head?: string;
+  dirty_paths: string[];
+  dirty_paths_truncated?: boolean;
+}
+
+export interface WorkflowRepoEvidence {
+  source: "engine";
+  before: WorkflowRepoSnapshot;
+  after: WorkflowRepoSnapshot;
+  drift: {
+    branch_changed: boolean;
+    head_changed: boolean;
+    dirty_paths_added: string[];
+    dirty_paths_cleared: string[];
+    dirty_paths_retained: string[];
+    /** True when snapshots cannot prove whether every retained dirty path changed. */
+    incomplete: boolean;
+    note?: string;
+  };
+}
+
+export interface HarnessEvidenceCoverage {
+  harness: HarnessName;
+  tool_evidence: {
+    support: "supported" | "partial" | "unsupported" | "unknown";
+    note?: string;
+  };
+  observed: {
+    final_results: number;
+    session_ids: number;
+    costs: number;
+  };
+}
+
+export interface WorkflowProofUnknown {
+  code:
+    | "tool_evidence_unavailable"
+    | "harness_capability_unregistered"
+    | "agent_cost_unreported"
+    | "agent_session_unreported"
+    | "repository_drift_incomplete";
+  message: string;
+  harness?: HarnessName;
+  agent_id?: string;
+}
+
+export interface WorkflowProof {
+  schema_version: typeof WORKFLOW_PROOF_SCHEMA_VERSION;
+  run: {
+    id: string;
+    name: string;
+    status: WorkflowRunStatus;
+    started_at: string;
+    ended_at: string;
+    duration_ms: number;
+    objective?: string;
+    error?: string;
+    result?: ResultDigest;
+  };
+  acceptance: {
+    criteria: AcceptanceResult[];
+    summary: AcceptanceSummary;
+  };
+  agents: WorkflowAgentProof[];
+  evidence: WorkflowEvidenceRecord[];
+  repository: WorkflowRepoEvidence;
+  harnesses: HarnessEvidenceCoverage[];
+  unknowns: WorkflowProofUnknown[];
+  integrity: {
+    journal: {
+      path: "journal.jsonl";
+      sha256: string;
+      bytes: number;
+    };
+  };
+}
+
+export interface HarnessEvidenceCapability {
+  toolEvidence: HarnessEvidenceCoverage["tool_evidence"];
+}
+
 /** JSON-schema *subset* accepted by stage gates (see validate.ts). */
 export interface StageSchema {
   type: "object" | "array" | "string" | "number" | "boolean";
@@ -28,6 +186,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 +204,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 +225,7 @@ export interface SpawnResult {
 export interface SpawnRequest {
   prompt: string;
   model?: string;
+  effort?: string;
   timeoutMs: number;
   maxTurns: number;
   cwd: string;
@@ -87,11 +252,15 @@ export interface WorkflowContext {
   stage: (title: string) => void;
   /** Narrate progress (stderr + journal). */
   log: (message: string) => void;
+  /** Attach a bounded, sourced receipt to the run and optional acceptance criteria. */
+  evidence: (input: WorkflowEvidenceInput) => string;
 }
 
 export interface WorkflowMeta {
   name: string;
   description?: string;
+  objective?: string;
+  acceptance?: AcceptanceCriterion[];
 }
 
 /** Loaded script shape: `export const meta` + `export default async (ctx) => …`. */
@@ -105,7 +274,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.
@@ -131,6 +300,9 @@ export interface EngineOpts {
   allowApiBilling?: boolean;
   /** Billing-probe override for tests (default: the real probeBilling). */
   probeBilling?: BillingProber;
+  /** Capability claims used to state whether adapter-native tool evidence was
+   * available. Missing claims remain unknown. */
+  harnessEvidence?: Readonly<Record<HarnessName, HarnessEvidenceCapability | undefined>>;
 }
 
 export interface RunReport {
@@ -144,6 +316,8 @@ export interface RunReport {
   costUsd: number;
   durationMs: number;
   journalPath: string;
+  proofPath: string;
+  acceptance: AcceptanceSummary;
   /** 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. */

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"] : [];
+}