omp-conductor 0.2.0

package/src/worker.ts

@@ -0,0 +1,292 @@
+/**
+ * Runs exactly one omp coding session for one issue, under caps this file
+ * enforces itself.
+ *
+ * The caps are the point. A worker that is *asked* to respect a turn budget
+ * will talk itself out of it around turn 80, so the ceiling lives out here:
+ * count the turns, watch the clock, and abort the session. Likewise the final
+ * state is parsed out of the worker's own report rather than trusted — an
+ * unreadable report is a failure, because the alternative is unverified work
+ * sliding into a merge queue.
+ */
+
+import { createSession, disposeSession } from "./omp.ts";
+import type { Caps, RunState } from "./types.ts";
+
+/** A PR link the worker pushed, recognised anywhere in its report. */
+const PR_URL_PATTERN = /https:\/\/github\.com\/\S+\/pull\/\d+/;
+
+/** `{{KEY}}` placeholders in a brief template. */
+const PLACEHOLDER_PATTERN = /\{\{([A-Za-z0-9_]+)\}\}/g;
+
+/**
+ * Which ceiling stopped a run. Only ever set alongside `state: "killed"`: the
+ * turn counter caught a loop, or the wall clock caught a session that was stuck
+ * without spending turns.
+ */
+export type KilledBy = "turns" | "wallclock";
+
+export interface WorkerOpts {
+  brief: string;
+  cwd: string;
+  caps: Caps;
+  /**
+   * Directory the harness writes this run's transcript into — a directory, not
+   * a file. The SDK takes no `sessionFile` input, so naming a path here would
+   * only name one nothing ever writes to. Omitted, the harness picks its own
+   * location; either way the real path comes back on {@link WorkerResult}.
+   */
+  sessionDir?: string;
+  /**
+   * Model pattern for this session, in omp's model/role syntax. Omitted leaves
+   * the harness to pick, which is what an unconfigured project wants.
+   */
+  model?: string;
+  onTurn?: (n: number) => void;
+}
+
+/**
+ * The one collaborator worth injecting: starting a session is the only thing
+ * `runWorker` does that needs a real harness. Defaulted, so production callers
+ * never pass it and a test can hand over a fake without a live peer dependency.
+ */
+export interface RunWorkerDeps {
+  createSession: typeof createSession;
+}
+
+export interface WorkerResult {
+  state: RunState;
+  prUrl?: string;
+  turns: number;
+  spendUsd: number;
+  report: string;
+  killedBy?: KilledBy;
+  /**
+   * Transcript the session actually opened, absent if it opened none. Recorded
+   * per run because it is the only readable evidence left once the worktree is
+   * cleaned up.
+   */
+  sessionFile?: string;
+  /**
+   * Set when the harness could not honour {@link WorkerOpts.model} and used
+   * another. Carried out rather than swallowed: a run that quietly read dumber
+   * is otherwise indistinguishable from a run that was merely unlucky.
+   */
+  modelFallbackMessage?: string;
+}
+
+/**
+ * Fill `{{KEY}}` placeholders from `vars`.
+ *
+ * An unknown key is left verbatim rather than blanked: a brief that reads
+ * `Fix {{ISSUE}}` is obviously broken to whoever reads the transcript, whereas
+ * `Fix undefined` looks like an instruction.
+ */
+export function renderBrief(template: string, vars: Record<string, string>): string {
+  return template.replace(PLACEHOLDER_PATTERN, (placeholder, key: string) => {
+    // Own properties only, so `{{constructor}}` cannot reach up the prototype.
+    if (!Object.hasOwn(vars, key)) return placeholder;
+    const value = vars[key];
+    return value === undefined ? placeholder : value;
+  });
+}
+
+/**
+ * Read the run's outcome out of the worker's final report.
+ *
+ * Success has to be claimed explicitly (`pushed-green`); everything else,
+ * including an empty or unparseable report, is a failure. Defaulting the other
+ * way would let a session that died mid-thought be reported as merge-ready.
+ */
+export function deriveResult(report: string): { state: RunState; prUrl?: string } {
+  const haystack = report.toLowerCase();
+  const state: RunState = haystack.includes("pushed-green")
+    ? "pushed-green"
+    : haystack.includes("ci-red")
+      ? "failed"
+      : haystack.includes("blocked")
+        ? "blocked"
+        : "failed";
+  const prUrl = PR_URL_PATTERN.exec(report)?.[0];
+  return prUrl === undefined ? { state } : { state, prUrl };
+}
+
+/**
+ * Is this `agent_end` the end of the run?
+ *
+ * `isTerminal: false` means the harness will resume the session for maintenance
+ * or async delivery, so the messages so far are a snapshot rather than a
+ * result: completing there truncates the worker mid-flight and reports a
+ * partial run as final. An absent field is terminal — that is what older
+ * harness builds send, and treating it as non-terminal would hang every run.
+ *
+ * Exported because it is the one seam that lets this rule be tested without
+ * standing up an SDK session.
+ */
+export function shouldComplete(event: { isTerminal?: boolean }): boolean {
+  return event.isTerminal !== false;
+}
+
+/**
+ * Drive one session to completion, a cap, or a failure. Never throws for a
+ * failed run — a rejected `prompt()` is reported as `state: "failed"` so the
+ * dispatcher's retry/escalate logic has one shape to reason about.
+ */
+export async function runWorker(
+  o: WorkerOpts,
+  deps: RunWorkerDeps = { createSession },
+): Promise<WorkerResult> {
+  // Read the caps once, by value: `o.caps` belongs to the caller's config.
+  const { workerMaxTurns, workerWallClockMs } = o.caps;
+
+  const session = await deps.createSession({
+    cwd: o.cwd,
+    ...(o.sessionDir === undefined ? {} : { sessionDir: o.sessionDir }),
+    ...(o.model === undefined ? {} : { model: o.model }),
+  });
+
+  // Every exit below reports the session's own facts the same way: the
+  // transcript it actually opened, and any model downgrade it announced. Read at
+  // return time so a session that materialises either late is still reported
+  // honestly.
+  const withSessionFacts = (result: WorkerResult): WorkerResult => {
+    const { sessionFile, modelFallbackMessage } = session;
+    return {
+      ...result,
+      ...(sessionFile === undefined ? {} : { sessionFile }),
+      ...(modelFallbackMessage === undefined ? {} : { modelFallbackMessage }),
+    };
+  };
+
+  let turns = 0;
+  let spendUsd = 0;
+  let report = "";
+  let killedBy: KilledBy | undefined;
+  // Bun's global timer handle; cleared on every exit path below.
+  let timer: Timer | undefined;
+  // Resolved by the first terminal `agent_end`, and by every cap kill. Only
+  // ever awaited when the harness has already said it is not finished.
+  const { promise: settled, resolve: settle } = Promise.withResolvers<void>();
+  // Set by a non-terminal `agent_end`: the harness will resume this session.
+  let resuming = false;
+
+  const clearWallClock = () => {
+    if (timer === undefined) return;
+    clearTimeout(timer);
+    timer = undefined;
+  };
+
+  const kill = (by: KilledBy) => {
+    if (killedBy !== undefined) return;
+    killedBy = by;
+    clearWallClock();
+    session.abort();
+    // An aborted session may never reach a terminal `agent_end`. The cap is the
+    // outcome now, so nothing may still be waiting for one.
+    settle();
+  };
+
+  session.on("turn_start", () => {
+    // The documented watchdog signal, and the honest one: `turn_start` fires
+    // exactly once per turn, whereas one turn can emit several assistant
+    // `message_end`s and would burn the cap on a run that is behaving.
+    turns += 1;
+    o.onTurn?.(turns);
+    if (turns > workerMaxTurns) kill("turns");
+  });
+
+  session.on("message_end", (event) => {
+    const message = field(event, "message");
+    if (field(message, "role") !== "assistant") return;
+    // Keep the newest non-empty assistant text: whatever the worker said last
+    // is its report, whether it finished cleanly or was cut off.
+    const text = reportText(field(message, "content"));
+    if (text !== "") report = text;
+  });
+
+  session.on("agent_end", (event) => {
+    // ponytail: cost only arrives when the harness run carries telemetry, so
+    // spend can legitimately read 0 and the daily-spend cap then leans on the
+    // turn and wall-clock ceilings. Upgrade path: pass a telemetry config
+    // through `createSession` once the harness exposes it on the SDK options.
+    const estimated = field(field(field(event, "telemetry"), "cost"), "estimatedUsd");
+    if (typeof estimated === "number" && Number.isFinite(estimated)) spendUsd += estimated;
+
+    // Anything that is not literally `false` — including garbage or nothing at
+    // all — is a finished run.
+    const isTerminal = field(event, "isTerminal");
+    if (shouldComplete(typeof isTerminal === "boolean" ? { isTerminal } : {})) {
+      settle();
+      return;
+    }
+    resuming = true;
+  });
+
+  // A stuck session spends no turns, so turns alone cannot detect it. The
+  // callback does not drop the handle itself: every exit runs `clearWallClock()`
+  // exactly once instead, and clearing an already-fired handle is a documented
+  // no-op — cheaper than assuming a fired timer holds nothing.
+  timer = setTimeout(() => kill("wallclock"), workerWallClockMs);
+
+  try {
+    await session.prompt(o.brief);
+    // `prompt()` returning is not the end of the run once the harness has
+    // announced a resume: finishing here would hand back a truncated report as
+    // the final result. Wait for the terminal `agent_end`, or for a cap.
+    if (resuming && killedBy === undefined) await settled;
+  } catch (cause) {
+    // Our own abort surfaces here on some paths; that is a kill, not a crash.
+    if (killedBy === undefined) {
+      const detail = cause instanceof Error ? cause.message : String(cause);
+      return withSessionFacts({
+        state: "failed",
+        turns,
+        spendUsd,
+        report: report === "" ? detail : report,
+      });
+    }
+  } finally {
+    // Runs on every exit, including the early return above: a live timer keeps
+    // the dispatcher process alive long after the run it was guarding.
+    clearWallClock();
+    try {
+      await disposeSession(session);
+    } catch {
+      // Teardown noise must not overwrite the run's actual outcome.
+    }
+  }
+
+  if (killedBy !== undefined) {
+    return withSessionFacts({ state: "killed", turns, spendUsd, report, killedBy });
+  }
+
+  const { state, prUrl } = deriveResult(report);
+  return withSessionFacts(
+    prUrl === undefined
+      ? { state, turns, spendUsd, report }
+      : { state, prUrl, turns, spendUsd, report },
+  );
+}
+
+/**
+ * Read one property off an unvalidated harness event. The event union lives in
+ * the peer dependency, so the worker narrows the handful of fields it reads
+ * instead of importing types it cannot see at build time.
+ */
+function field(source: unknown, key: string): unknown {
+  if (source === null || typeof source !== "object") return undefined;
+  return Reflect.get(source, key);
+}
+
+/** Flatten an assistant message's content blocks to their plain text. */
+function reportText(content: unknown): string {
+  if (typeof content === "string") return content.trim();
+  const blocks: readonly unknown[] = Array.isArray(content) ? content : [];
+  const parts: string[] = [];
+  for (const block of blocks) {
+    if (field(block, "type") !== "text") continue;
+    const text = field(block, "text");
+    if (typeof text === "string") parts.push(text);
+  }
+  return parts.join("\n").trim();
+}

package/src/worktree.ts

@@ -0,0 +1,303 @@
+/**
+ * Checkout provisioning for one run.
+ *
+ * Every issue gets its own working tree so two workers can never see each
+ * other's half-finished edits. The trees are cut from a per-repo bare mirror
+ * that is cloned once and refreshed, rather than a fresh full clone per issue:
+ * a module repo's history is fetched one time and every later run pays only
+ * for the delta.
+ */
+
+import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+
+import type { RepoTarget } from "./types.ts";
+
+/**
+ * Normal-clone fetch semantics. Deliberately *not* the mirror's own
+ * `+refs/*:refs/*`: see `configureMirror`.
+ */
+const TRACKING_REFSPEC = "+refs/heads/*:refs/remotes/origin/*";
+
+/** Matches the `user:token@` part of any URL, so it can be blanked out. */
+const URL_USERINFO = /([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)[^\s/@]+@/g;
+
+/**
+ * The on-disk layout, in one place. Both are pure functions of config, so a
+ * caller that has to clean up *before* provisioning — the dispatcher on a
+ * retry, or reconciling orphaned trees at startup — can name a mirror or a
+ * tree without a network hop, and cannot drift from what `ensureMirror` and
+ * `addWorktree` will actually create.
+ */
+export function mirrorPathFor(repo: RepoTarget, mirrorRoot: string): string {
+  return join(mirrorRoot, `${repo.name}.git`);
+}
+
+/** One tree per issue: a retry reuses the number, never the contents. */
+export function worktreePathFor(workspaceRoot: string, issue: number): string {
+  return join(workspaceRoot, String(issue));
+}
+
+/** One git invocation, decoded. Nothing here judges the exit code. */
+async function runGit(
+  args: string[],
+  cwd?: string,
+): Promise<{ code: number; stdout: string; stderr: string }> {
+  const proc = Bun.spawn(["git", ...args], {
+    cwd,
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "pipe",
+    // An unattended dispatcher must fail loudly rather than block forever on a
+    // credential prompt nobody is there to answer.
+    env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+  });
+
+  const [stdout, stderr, code] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+
+  return { code, stdout, stderr };
+}
+
+/**
+ * The one way this module runs git *for effect*. Non-zero exit throws with the
+ * argv, the exit code and stderr, because a bare "git failed" in a daemon log
+ * is worth nothing at 3am.
+ */
+async function git(args: string[], cwd?: string): Promise<string> {
+  const { code, stdout, stderr } = await runGit(args, cwd);
+
+  if (code !== 0) {
+    const where = cwd === undefined ? "" : ` (cwd ${cwd})`;
+    const detail = stderr.trim() || stdout.trim() || "no output";
+    // A clone URL can carry a token, and it lands in both our argv and git's
+    // own error text; this string reaches logs and humans, so scrub it.
+    throw new Error(
+      `git ${args.join(" ")}${where} exited ${code}: ${detail}`.replace(
+        URL_USERINFO,
+        "$1***@",
+      ),
+    );
+  }
+
+  return stdout.trim();
+}
+
+/**
+ * The way this module runs git *as a question*. For plumbing like `show-ref`
+ * a non-zero exit is the answer "no", not a failure, so it must not throw —
+ * otherwise every probe needs a try/catch that also swallows real breakage.
+ */
+async function gitSucceeds(args: string[], cwd?: string): Promise<boolean> {
+  const { code } = await runGit(args, cwd);
+  return code === 0;
+}
+
+/**
+ * Rewrites the two `clone --mirror` defaults that are actively dangerous for a
+ * cache we cut worktrees from. Applied on every `ensureMirror` so a mirror left
+ * by an older build heals itself instead of behaving differently forever.
+ *
+ * - `remote.origin.mirror=true` makes a bare `git push` from *any* worktree of
+ *   this repository behave as `push --mirror`, force-updating the remote from
+ *   our local refs and deleting whatever we do not happen to have. Worktrees
+ *   share the mirror's config, so that footgun is pointed straight at the
+ *   worker.
+ * - `fetch=+refs/*:refs/*` puts the upstream branches and our per-run branches
+ *   in the same namespace, so a `--prune` refresh would try to delete every run
+ *   branch that has not been pushed yet.
+ *
+ * With normal-clone semantics a refresh only ever moves `refs/remotes/origin/*`
+ * and cannot touch a live run.
+ */
+async function configureMirror(mirrorPath: string): Promise<void> {
+  await git(
+    ["config", "--replace-all", "remote.origin.mirror", "false"],
+    mirrorPath,
+  );
+  await git(
+    ["config", "--replace-all", "remote.origin.fetch", TRACKING_REFSPEC],
+    mirrorPath,
+  );
+}
+
+/**
+ * Returns the path of the bare mirror for `repo`, cloning it on first use and
+ * refreshing it otherwise.
+ *
+ * ponytail: no cross-process lock. Two dispatch loops that call this for the
+ * same repo at the same instant can collide on git's ref locks and one will
+ * throw; the run is retried rather than corrupted. Upgrade path is a lockfile
+ * in `mirrorRoot` keyed by repo name.
+ *
+ * ponytail: if `repo.cloneUrl` embeds credentials, `git clone` persists them in
+ * the mirror's config, exactly as it would for a hand-run clone. Prefer an SSH
+ * URL or an https URL backed by a credential helper.
+ */
+export async function ensureMirror(
+  repo: RepoTarget,
+  mirrorRoot: string,
+): Promise<string> {
+  mkdirSync(mirrorRoot, { recursive: true });
+  const mirrorPath = mirrorPathFor(repo, mirrorRoot);
+
+  if (existsSync(mirrorPath)) {
+    await configureMirror(mirrorPath);
+    await git(["remote", "update", "--prune"], mirrorPath);
+    return mirrorPath;
+  }
+
+  try {
+    await git(["clone", "--mirror", repo.cloneUrl, mirrorPath]);
+  } catch (err) {
+    // A half-written mirror would be seen as "present" by the next call and
+    // fail in a much more confusing place. Retry from scratch instead.
+    rmSync(mirrorPath, { recursive: true, force: true });
+    throw err;
+  }
+  await configureMirror(mirrorPath);
+  return mirrorPath;
+}
+
+/**
+ * Provisions `<workspaceRoot>/<issue>` as a worktree of `repo` for `branch`,
+ * and returns the path. On the first attempt the branch is cut from the
+ * upstream tip of the default branch; on a retry the preserved branch is
+ * reattached (see the comment on the add below).
+ *
+ * ponytail: reattachment is the only retry mode, so attempt 2 always inherits
+ * attempt 1's tip — including a half-finished or broken state it might rather
+ * start clean from. There is no "start from upstream but keep the old work"
+ * option because that needs somewhere safe to park the old tip first. Upgrade
+ * path: snapshot the branch to `refs/conductor/attempt/<issue>/<n>` before
+ * resetting the run branch to `base`, and surface both refs in the escalation.
+ */
+export async function addWorktree(
+  repo: RepoTarget,
+  mirrorRoot: string,
+  workspaceRoot: string,
+  issue: number,
+  branch: string,
+): Promise<string> {
+  const mirrorPath = await ensureMirror(repo, mirrorRoot);
+  mkdirSync(workspaceRoot, { recursive: true });
+
+  const worktreePath = worktreePathFor(workspaceRoot, issue);
+  if (existsSync(worktreePath)) {
+    // Reusing a tree is how one worker silently inherits another attempt's
+    // uncommitted edits and pushes them under this issue's name.
+    throw new Error(
+      `worktree path already exists: ${worktreePath}. Refusing to reuse it — ` +
+        `it may hold a previous attempt's uncommitted work. Call ` +
+        `removeWorktree(${mirrorPath}, ${worktreePath}) first.`,
+    );
+  }
+
+  // The base ref has to be fetched by hand. The mirror's own copy of
+  // `refs/heads/<defaultBranch>` is whatever the last refresh left behind (and
+  // under normal-clone semantics is no longer refreshed at all), so branching
+  // off it would silently start a run on a stale tip.
+  const base = `refs/remotes/origin/${repo.defaultBranch}`;
+  await git(
+    [
+      "fetch",
+      "--no-tags",
+      "origin",
+      `+refs/heads/${repo.defaultBranch}:${base}`,
+    ],
+    mirrorPath,
+  );
+
+  // `--no-track` on the create path because the start point is a
+  // remote-tracking ref: without it git would set the run branch's upstream to
+  // the default branch, and the worker's `git push` would then argue with
+  // `push.default` instead of publishing the branch. The reattach path must
+  // *omit* the flag — git dies with "--[no-]track can only be used if a new
+  // branch is created" — and does not need it, since checking out an existing
+  // branch writes no tracking config at all.
+  //
+  // `-b` is only ever correct on the *first* attempt for an issue. Branch
+  // names are a deterministic function of the issue number, `removeWorktree`
+  // deliberately leaves the branch behind in the mirror, and `git worktree add
+  // -b <existing>` is a hard error — so without this probe a second attempt
+  // could never provision a tree and `maxAttemptsPerIssue` was fiction.
+  //
+  // The retry therefore *reattaches* the existing branch rather than doing
+  // either of the two easier things. A fresh `<branch>-attempt2` would break
+  // the fleet contract of one issue = one branch = one PR. A `branch -D` or a
+  // force-reset to the upstream tip would be irreversible: that branch can
+  // hold the only copy of work attempt 1 committed but never pushed. Attaching
+  // to it hands the new worker attempt 1's commits, so it can continue or
+  // recover them, and any destructive call stays a human's to make.
+  const branchExists = await gitSucceeds(
+    ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`],
+    mirrorPath,
+  );
+  const addArgs = branchExists
+    ? ["worktree", "add", worktreePath, branch]
+    : ["worktree", "add", "--no-track", "-b", branch, worktreePath, base];
+
+  try {
+    await git(addArgs, mirrorPath);
+  } catch (err) {
+    // A hard crash can leave the branch registered to a worktree whose
+    // directory is long gone, and git then refuses the add as "already checked
+    // out". `prune` drops exactly that stale bookkeeping and never touches a
+    // commit, so run it and retry once. It is not conditioned on git's wording
+    // because that text is version- and locale-dependent; an add that is
+    // broken for any other reason simply fails the same way twice.
+    await git(["worktree", "prune"], mirrorPath);
+    try {
+      await git(addArgs, mirrorPath);
+    } catch (retryErr) {
+      const first = err instanceof Error ? err.message : String(err);
+      const second =
+        retryErr instanceof Error ? retryErr.message : String(retryErr);
+      throw new Error(
+        `failed to provision worktree ${worktreePath} for issue ${issue} on ` +
+          `branch ${branch} (${branchExists ? "reattaching an existing branch" : "creating a new branch"}), ` +
+          `both before and after \`git worktree prune\`: ${second} ` +
+          `(first attempt: ${first})`,
+      );
+    }
+  }
+
+  return worktreePath;
+}
+
+/**
+ * Removes a run's worktree and its registration in the mirror. Idempotent: a
+ * path that is already gone resolves, so cleanup can be retried and can run on
+ * a run that never got as far as a checkout.
+ *
+ * ponytail: the run's branch stays in the mirror's `refs/heads/*`, since it may
+ * be the only copy of work that has not been pushed. Mirrors therefore grow one
+ * ref per run; upgrade path is reaping branches that are merged or have a
+ * closed PR.
+ */
+export async function removeWorktree(
+  mirrorPath: string,
+  worktreePath: string,
+): Promise<void> {
+  if (!existsSync(mirrorPath)) {
+    // No mirror means no registration left to clean up, and deleting a tree we
+    // can no longer prove we created is not this function's call.
+    return;
+  }
+
+  if (existsSync(worktreePath)) {
+    try {
+      await git(["worktree", "remove", "--force", worktreePath], mirrorPath);
+    } catch (err) {
+      // A path git does not recognise (hand-deleted, never registered) is fine
+      // for cleanup's purposes. A path that survives the attempt is not: the
+      // next run for this issue would trip over it.
+      if (existsSync(worktreePath)) throw err;
+    }
+  }
+
+  await git(["worktree", "prune"], mirrorPath);
+}