p-dev-harness 0.3.0 → 0.3.1

package/workspace-snapshot/files/src/cursor/run-observer.ts

@@ -0,0 +1,367 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { Agent, CursorAgentError, type Run, type RunResult, type SDKAgent } from "@cursor/sdk";
+import type { EventLogger } from "../artifacts/events.js";
+import { getCursorRunResultPath } from "../artifacts/paths.js";
+import { classifyCursorError, classifyRunResultStatus } from "./errors.js";
+import { extractTargetRepoGitResult, type CapturedGitResult } from "./git-result.js";
+import { extractRevisionGitResult } from "./revision-git-result.js";
+import { cancelCursorRun, type CursorCancelOutcome } from "./run-cleanup.js";
+import {
+  ImplementationError,
+  MergeError,
+  PlanningError,
+  PhaseError,
+  RevisionError,
+} from "../runner/errors.js";
+
+export type ObservePhase =
+  | "planning"
+  | "implementation"
+  | "revision"
+  | "integration_repair";
+
+export interface ObservedRunResult {
+  agentId: string;
+  runId: string;
+  result: RunResult;
+  assistantText: string;
+  gitResult: CapturedGitResult | null;
+  cancelOutcome: CursorCancelOutcome | null;
+}
+
+export interface SendAndObserveOptions {
+  phase?: ObservePhase;
+  targetRepo?: string;
+  expectedBranch?: string;
+  expectedPrUrl?: string;
+  abortSignal?: AbortSignal;
+  apiKey?: string;
+  pollIntervalMs?: number;
+  fetchCloudRun?: typeof Agent.getRun;
+  onAgentCreated?: (details: { agentId: string; runId: string }) => Promise<void>;
+}
+
+const DEFAULT_CLOUD_RUN_POLL_INTERVAL_MS = 5_000;
+
+export function isStreamUnavailableRunResult(
+  result: { status: string; error?: { code?: string; message?: string } | null },
+): boolean {
+  return (
+    result.status === "error" &&
+    result.error?.code === "stream_unavailable"
+  );
+}
+
+export function isTerminalRunStatus(status: string): boolean {
+  return (
+    status === "finished" ||
+    status === "completed" ||
+    status === "error" ||
+    status === "cancelled"
+  );
+}
+
+function sleep(ms: number, abortSignal?: AbortSignal): Promise<void> {
+  if (abortSignal?.aborted) {
+    return Promise.reject(abortSignal.reason);
+  }
+
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      abortSignal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(abortSignal?.reason);
+    };
+
+    abortSignal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+export async function pollCloudRunResult(
+  options: {
+    apiKey: string;
+    agentId: string;
+    runId: string;
+    abortSignal?: AbortSignal;
+    pollIntervalMs?: number;
+    fetchCloudRun?: typeof Agent.getRun;
+  },
+): Promise<RunResult> {
+  const fetchCloudRun = options.fetchCloudRun ?? Agent.getRun.bind(Agent);
+  const pollIntervalMs =
+    options.pollIntervalMs ?? DEFAULT_CLOUD_RUN_POLL_INTERVAL_MS;
+
+  while (true) {
+    if (options.abortSignal?.aborted) {
+      throw options.abortSignal.reason;
+    }
+
+    const snapshot = await fetchCloudRun(options.runId, {
+      runtime: "cloud",
+      agentId: options.agentId,
+      apiKey: options.apiKey,
+    });
+
+    if (
+      isTerminalRunStatus(snapshot.status) &&
+      !isStreamUnavailableRunResult(snapshot)
+    ) {
+      return snapshot as RunResult;
+    }
+
+    await sleep(pollIntervalMs, options.abortSignal);
+  }
+}
+
+function makePhaseError(
+  phase: ObservePhase,
+  classification: NonNullable<import("../types/run.js").ErrorClassification>,
+  message: string,
+  cancelOutcome: CursorCancelOutcome | null = null,
+): PhaseError {
+  if (phase === "implementation") {
+    return new ImplementationError(classification, message, cancelOutcome);
+  }
+  if (phase === "revision") {
+    return new RevisionError(classification, message, cancelOutcome);
+  }
+  if (phase === "integration_repair") {
+    return new MergeError(classification, message);
+  }
+  return new PlanningError(classification, message, cancelOutcome);
+}
+
+async function abortRun(
+  phase: ObservePhase,
+  abortSignal: AbortSignal,
+  ensureCancelled: () => Promise<CursorCancelOutcome>,
+): Promise<never> {
+  const cancelOutcome = await ensureCancelled();
+  const reason = abortSignal.reason;
+  if (reason instanceof PhaseError) {
+    throw makePhaseError(
+      phase,
+      reason.classification ?? "cursor_run_timeout",
+      reason.message,
+      cancelOutcome,
+    );
+  }
+
+  throw makePhaseError(
+    phase,
+    "cursor_run_timeout",
+    reason instanceof Error ? reason.message : "Cursor run aborted",
+    cancelOutcome,
+  );
+}
+
+function attachAbortHandler(
+  abortSignal: AbortSignal | undefined,
+  ensureCancelled: () => Promise<CursorCancelOutcome>,
+): () => void {
+  if (!abortSignal) {
+    return () => undefined;
+  }
+
+  const onAbort = () => {
+    void ensureCancelled();
+  };
+
+  abortSignal.addEventListener("abort", onAbort, { once: true });
+  return () => abortSignal.removeEventListener("abort", onAbort);
+}
+
+export async function sendAndObserve(
+  agent: SDKAgent,
+  prompt: string,
+  runDirectory: string,
+  events: EventLogger,
+  options: SendAndObserveOptions = {},
+): Promise<ObservedRunResult> {
+  const phase = options.phase ?? "planning";
+  const agentId = agent.agentId;
+  let run: Run;
+  let detachAbort: (() => void) | undefined;
+  let cancelOutcome: CursorCancelOutcome | null = null;
+  let cancelPromise: Promise<CursorCancelOutcome> | null = null;
+
+  const ensureCancelled = (): Promise<CursorCancelOutcome> => {
+    if (cancelOutcome !== null) {
+      return Promise.resolve(cancelOutcome);
+    }
+    if (!cancelPromise) {
+      cancelPromise = cancelCursorRun(run, events).then((outcome) => {
+        cancelOutcome = outcome;
+        return outcome;
+      });
+    }
+    return cancelPromise;
+  };
+
+  try {
+    run = await agent.send(prompt);
+  } catch (error) {
+    const classification = classifyCursorError(error);
+    throw makePhaseError(
+      phase,
+      classification ?? "cursor_api_failure",
+      error instanceof Error ? error.message : String(error),
+    );
+  }
+
+  await events.log("cursor_agent_created", "info", { agentId, runId: run.id });
+  if (options.onAgentCreated) {
+    await options.onAgentCreated({ agentId, runId: run.id });
+  }
+  detachAbort = attachAbortHandler(options.abortSignal, ensureCancelled);
+  if (options.abortSignal?.aborted) {
+    await abortRun(phase, options.abortSignal, ensureCancelled);
+  }
+
+  try {
+    for await (const event of run.stream()) {
+      if (options.abortSignal?.aborted) {
+        await abortRun(phase, options.abortSignal, ensureCancelled);
+      }
+      await events.log("cursor_event", "info", {
+        type: event.type,
+      });
+    }
+  } catch (error) {
+    if (options.abortSignal?.aborted) {
+      await abortRun(phase, options.abortSignal, ensureCancelled);
+    }
+    if (error instanceof PhaseError) {
+      throw error;
+    }
+    // Streaming is best-effort; wait() is authoritative.
+  }
+
+  if (options.abortSignal?.aborted) {
+    await abortRun(phase, options.abortSignal, ensureCancelled);
+  }
+
+  let result: RunResult;
+  try {
+    result = await run.wait();
+    if (
+      options.apiKey &&
+      agentId.startsWith("bc-") &&
+      isStreamUnavailableRunResult(result)
+    ) {
+      await events.log("cursor_run_poll_fallback", "info", {
+        runId: result.id,
+        agentId,
+      });
+      result = await pollCloudRunResult({
+        apiKey: options.apiKey,
+        agentId,
+        runId: result.id,
+        abortSignal: options.abortSignal,
+        pollIntervalMs: options.pollIntervalMs,
+        fetchCloudRun: options.fetchCloudRun,
+      });
+    }
+  } catch (error) {
+    if (options.abortSignal?.aborted) {
+      await abortRun(phase, options.abortSignal, ensureCancelled);
+    }
+    if (error instanceof CursorAgentError) {
+      throw makePhaseError(phase, "cursor_api_failure", error.message);
+    }
+    throw error;
+  } finally {
+    detachAbort?.();
+  }
+
+  if (options.abortSignal?.aborted) {
+    await abortRun(phase, options.abortSignal, ensureCancelled);
+  }
+
+  await mkdir(`${runDirectory}/cursor`, { recursive: true });
+  await writeFile(
+    getCursorRunResultPath(runDirectory),
+    `${JSON.stringify(
+      {
+        id: result.id,
+        status: result.status,
+        durationMs: result.durationMs,
+        model: result.model,
+        git: result.git,
+        error: result.error,
+        usage: result.usage,
+      },
+      null,
+      2,
+    )}\n`,
+    "utf8",
+  );
+
+  await events.log("cursor_run_finished", "info", {
+    runId: result.id,
+    status: result.status,
+    durationMs: result.durationMs,
+  });
+
+  const failureClass = classifyRunResultStatus(result.status);
+  if (failureClass) {
+    throw makePhaseError(
+      phase,
+      failureClass,
+      result.error?.message ?? `Cursor run ended with status ${result.status}`,
+    );
+  }
+
+  const assistantText = result.result?.trim() ?? "";
+  if (!assistantText) {
+    throw makePhaseError(
+      phase,
+      "cursor_run_failed",
+      "Cursor run finished without assistant text",
+    );
+  }
+
+  const gitBranches = result.git?.branches ?? [];
+  const hasBranchOrPr = gitBranches.some((b) => b.branch || b.prUrl);
+  if (phase === "planning" && hasBranchOrPr) {
+    throw new PlanningError(
+      "agent_policy_violation",
+      "Planning agent created a branch or PR despite read-only constraints",
+    );
+  }
+
+  let gitResult: CapturedGitResult | null = null;
+  if (phase === "implementation") {
+    gitResult = extractTargetRepoGitResult(result.git, options.targetRepo ?? "");
+  } else if (phase === "revision" || phase === "integration_repair") {
+    try {
+      gitResult = extractRevisionGitResult(
+        result.git,
+        options.targetRepo ?? "",
+        options.expectedBranch ?? "",
+        options.expectedPrUrl ?? "",
+      );
+    } catch (error) {
+      if (phase === "integration_repair" && error instanceof RevisionError) {
+        throw new MergeError(
+          error.classification ?? "cursor_branch_attach_failure",
+          error.message,
+        );
+      }
+      throw error;
+    }
+  }
+
+  return {
+    agentId,
+    runId: result.id,
+    result,
+    assistantText,
+    gitResult,
+    cancelOutcome,
+  };
+}

package/workspace-snapshot/files/src/cursor/urls.ts

@@ -0,0 +1,19 @@
+const CURSOR_CLOUD_BASE_URL = "https://cursor.com/agents";
+
+export function buildCursorCloudRunUrl(
+  agentId: string,
+  runId?: string | null,
+): string {
+  const url = new URL(`${CURSOR_CLOUD_BASE_URL}/${encodeURIComponent(agentId)}`);
+  if (runId) {
+    url.searchParams.set("run", runId);
+  }
+  return url.toString();
+}
+
+export function formatCursorCloudRunLink(
+  agentId: string,
+  runId?: string | null,
+): string {
+  return `[Cursor Cloud run](${buildCursorCloudRunUrl(agentId, runId)})`;
+}

package/workspace-snapshot/files/src/fixture/frontmatter.ts

@@ -0,0 +1,56 @@
+export interface FixtureMetadata {
+  title: string;
+  status: string | null;
+  projectName: string | null;
+  teamName: string | null;
+}
+
+export function parseFixtureMarkdown(raw: string): {
+  metadata: FixtureMetadata;
+  body: string;
+} {
+  const frontmatterMatch = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!frontmatterMatch) {
+    return {
+      metadata: {
+        title: "Fixture issue",
+        status: null,
+        projectName: null,
+        teamName: null,
+      },
+      body: raw,
+    };
+  }
+
+  const metadata: FixtureMetadata = {
+    title: "Fixture issue",
+    status: null,
+    projectName: null,
+    teamName: null,
+  };
+
+  for (const line of frontmatterMatch[1]!.split("\n")) {
+    const match = line.match(/^([A-Za-z]+):\s*(.*)$/);
+    if (!match) continue;
+    const key = match[1]!.toLowerCase();
+    const value = match[2]!.trim().replace(/^["']|["']$/g, "");
+    switch (key) {
+      case "title":
+        metadata.title = value;
+        break;
+      case "status":
+        metadata.status = value || null;
+        break;
+      case "projectname":
+        metadata.projectName = value || null;
+        break;
+      case "teamname":
+        metadata.teamName = value || null;
+        break;
+      default:
+        break;
+    }
+  }
+
+  return { metadata, body: frontmatterMatch[2]! };
+}

package/workspace-snapshot/files/src/github/actions-url.ts

@@ -0,0 +1,13 @@
+export function getGitHubActionsRunUrl(): string | null {
+  const serverUrl = process.env.GITHUB_SERVER_URL;
+  const repository = process.env.GITHUB_REPOSITORY;
+  const runId = process.env.GITHUB_RUN_ID;
+  if (!serverUrl || !repository || !runId) {
+    return null;
+  }
+  return `${serverUrl}/${repository}/actions/runs/${runId}`;
+}
+
+export function formatGitHubActionsRunLink(url: string): string {
+  return `[GitHub Actions run](${url})`;
+}

package/workspace-snapshot/files/src/github/base-branch.ts

@@ -0,0 +1,120 @@
+import type { GitHubClient } from "./client.js";
+import { GitHubApiError } from "./client.js";
+
+export interface ParsedGitHubRepoUrl {
+  owner: string;
+  repo: string;
+}
+
+export function parseGitHubRepoUrl(repoUrl: string): ParsedGitHubRepoUrl | null {
+  const match = repoUrl
+    .trim()
+    .match(/^https:\/\/github\.com\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)\/?$/);
+  if (!match) {
+    return null;
+  }
+  return { owner: match[1], repo: match[2] };
+}
+
+export async function assertBaseBranchExists(
+  client: GitHubClient,
+  targetRepo: string,
+  baseBranch: string,
+): Promise<void> {
+  const parsed = parseGitHubRepoUrl(targetRepo);
+  if (!parsed) {
+    throw new Error(`wrong_target_repo: Invalid GitHub repo URL: ${targetRepo}`);
+  }
+
+  try {
+    await client.getBranchRef(parsed.owner, parsed.repo, baseBranch);
+  } catch (error) {
+    if (error instanceof GitHubApiError && error.status === 404) {
+      throw new Error(
+        `base_branch_missing: Target repo ${targetRepo} does not have base branch "${baseBranch}". Create the branch or update repos[].baseBranch before running the harness.`,
+      );
+    }
+    throw error;
+  }
+}
+
+export async function assertHeadBranchWritePermission(
+  client: GitHubClient,
+  targetRepo: string,
+): Promise<void> {
+  const parsed = parseGitHubRepoUrl(targetRepo);
+  if (!parsed) {
+    throw new Error(`wrong_target_repo: Invalid GitHub repo URL: ${targetRepo}`);
+  }
+
+  try {
+    const repo = await client.getRepository(parsed.owner, parsed.repo);
+    if (repo.permissions?.push === true || repo.permissions?.admin === true) {
+      return;
+    }
+  } catch (error) {
+    if (error instanceof GitHubApiError && error.status === 401) {
+      throw error;
+    }
+    if (error instanceof GitHubApiError && error.status === 403) {
+      throw new Error(
+        `repair_head_branch_write_denied: HARNESS_GITHUB_TOKEN cannot verify write access for ${targetRepo}. Grant classic repo scope, or fine-grained Contents: Read and write plus Pull requests: Read and write on the target repo.`,
+      );
+    }
+    throw error;
+  }
+
+  throw new Error(
+    `repair_head_branch_write_denied: HARNESS_GITHUB_TOKEN lacks PR head-branch write access for ${targetRepo}. Grant classic repo scope, or fine-grained Contents: Read and write plus Pull requests: Read and write on the target repo.`,
+  );
+}
+
+export function assertPrBaseBranchMatches(input: {
+  prUrl: string;
+  actualBaseBranch: string;
+  expectedBaseBranch: string;
+}): void {
+  if (input.actualBaseBranch === input.expectedBaseBranch) {
+    return;
+  }
+
+  throw new Error(
+    `wrong_pr_base_branch: PR ${input.prUrl} targets "${input.actualBaseBranch}"; expected "${input.expectedBaseBranch}". Update the PR base branch before continuing.`,
+  );
+}
+
+export function assertPullRequestMergeable(input: {
+  prUrl: string;
+  merged: boolean;
+  mergeable: boolean | null;
+  mergeableState: string | null;
+  baseBranch: string;
+}): void {
+  if (input.merged) {
+    return;
+  }
+
+  const state = input.mergeableState?.toLowerCase() ?? null;
+  if (state === "dirty" || state === "behind" || state === "blocked") {
+    throw new Error(
+      `pr_not_mergeable: PR ${input.prUrl} is ${state} against "${input.baseBranch}". Update or rebase the PR branch after other merges land, then retry.`,
+    );
+  }
+
+  if (input.mergeable === false) {
+    throw new Error(
+      `pr_not_mergeable: PR ${input.prUrl} is not mergeable into "${input.baseBranch}". Resolve conflicts or update the branch, then retry.`,
+    );
+  }
+}
+
+export function isIntegrationRepairEligible(input: {
+  mergeable: boolean | null;
+  mergeableState: string | null;
+}): boolean {
+  const state = input.mergeableState?.toLowerCase() ?? null;
+  if (state === "blocked" || state === "unstable") {
+    return false;
+  }
+  return state === "dirty" || state === "behind" || input.mergeable === false;
+}

package/workspace-snapshot/files/src/github/check-policy.ts

@@ -0,0 +1,108 @@
+import type { HarnessConfig } from "../config/types.js";
+import type { PrCheckInfo } from "./pr-inspector.js";
+import type { ErrorClassification } from "../types/run.js";
+import {
+  DEFAULT_MERGE_ALLOW_NEUTRAL_CHECKS,
+  DEFAULT_MERGE_ALLOW_PENDING_CHECKS,
+  DEFAULT_MERGE_ALLOW_UNKNOWN_CHECKS,
+} from "../config/defaults.js";
+
+export type CheckPolicyDecision = "allow" | "block";
+
+export interface CheckPolicyResult {
+  decision: CheckPolicyDecision;
+  classification: ErrorClassification;
+  reason: string;
+  warnings: string[];
+}
+
+const FAILING_CONCLUSIONS = new Set([
+  "failure",
+  "cancelled",
+  "timed_out",
+  "action_required",
+]);
+
+const NEUTRAL_CONCLUSIONS = new Set(["neutral", "skipped", "success"]);
+
+export function evaluateChecksForMerge(
+  checks: PrCheckInfo[],
+  config: HarnessConfig,
+): CheckPolicyResult {
+  const allowPending =
+    config.merge?.allowPendingChecks ?? DEFAULT_MERGE_ALLOW_PENDING_CHECKS;
+  const allowUnknown =
+    config.merge?.allowUnknownChecks ?? DEFAULT_MERGE_ALLOW_UNKNOWN_CHECKS;
+  const allowNeutral =
+    config.merge?.allowNeutralChecks ?? DEFAULT_MERGE_ALLOW_NEUTRAL_CHECKS;
+
+  if (checks.length === 0) {
+    if (allowUnknown) {
+      return {
+        decision: "allow",
+        classification: null,
+        reason: "No check runs reported; proceeding per allowUnknownChecks",
+        warnings: ["No GitHub check runs reported for the PR head commit"],
+      };
+    }
+    return {
+      decision: "block",
+      classification: "checks_unknown",
+      reason: "No GitHub check runs reported for the PR head commit",
+      warnings: [],
+    };
+  }
+
+  const failing = checks.filter(
+    (check) =>
+      check.conclusion !== null && FAILING_CONCLUSIONS.has(check.conclusion),
+  );
+  if (failing.length > 0) {
+    return {
+      decision: "block",
+      classification: "checks_failing",
+      reason: `Failing checks: ${failing.map((c) => c.name).join(", ")}`,
+      warnings: [],
+    };
+  }
+
+  const pending = checks.filter(
+    (check) => check.status !== "completed" || check.conclusion === null,
+  );
+  if (pending.length > 0) {
+    if (allowPending) {
+      return {
+        decision: "allow",
+        classification: null,
+        reason: "Pending checks present; proceeding per allowPendingChecks",
+        warnings: pending.map((c) => `Pending check: ${c.name}`),
+      };
+    }
+    return {
+      decision: "block",
+      classification: "checks_pending",
+      reason: `Pending checks: ${pending.map((c) => c.name).join(", ")}`,
+      warnings: [],
+    };
+  }
+
+  const nonNeutral = checks.filter(
+    (check) =>
+      check.conclusion !== null && !NEUTRAL_CONCLUSIONS.has(check.conclusion),
+  );
+  if (nonNeutral.length > 0 && !allowNeutral) {
+    return {
+      decision: "block",
+      classification: "checks_unknown",
+      reason: `Unrecognized check conclusions: ${nonNeutral.map((c) => `${c.name}=${c.conclusion}`).join(", ")}`,
+      warnings: [],
+    };
+  }
+
+  return {
+    decision: "allow",
+    classification: null,
+    reason: "Checks policy passed",
+    warnings: [],
+  };
+}