omp-conductor 0.9.1 → 0.12.0

package/src/worker.ts

@@ -19,9 +19,17 @@ const HEAD_SHA_PATTERN = /^head:\s*([0-9a-f]{40})\s*$/im;
 const PUSHED_GREEN_PATTERN = /^state:\s*pushed-green\s*$/im;
 const BLOCKED_PATTERN = /^state:\s*blocked\s*$/im;
 
+/** Any explicit verdict line, whatever it claims. */
+const STATE_LINE_PATTERN = /^state:\s*\S+\s*$/im;
+
 /** `{{KEY}}` placeholders in a brief template. */
 const PLACEHOLDER_PATTERN = /\{\{([A-Za-z0-9_]+)\}\}/g;
 
+function scheduleWallClock(callback: () => void, delayMs: number): () => void {
+  const timer = setTimeout(callback, delayMs);
+  return () => clearTimeout(timer);
+}
+
 /**
  * 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
@@ -29,6 +37,24 @@ const PLACEHOLDER_PATTERN = /\{\{([A-Za-z0-9_]+)\}\}/g;
  */
 export type KilledBy = "turns" | "wallclock";
 
+export type WorkerPausePhase = "running" | "pausing" | "paused";
+
+export interface WorkerPauseControl {
+  phase(): WorkerPausePhase;
+  /** Cooperative park; resolves when the harness is idle. Rejects when the
+   * run is settling, cap-killed, or already pausing/paused. */
+  pause(): Promise<void>;
+  /** Returns a parked session to work with a continuation prompt. Throws
+   * when the phase is not `paused`. */
+  resume(): void;
+}
+
+/** What a resumed session is told. One literal so tests can pin it. */
+export const RESUME_PROMPT =
+  "The operator paused this session and has now resumed it. Continue exactly where you left off: " +
+  "re-check the outcome of your last action before repeating it, then keep working your original " +
+  "brief to the same report contract.";
+
 export interface WorkerOpts {
   brief: string;
   cwd: string;
@@ -84,15 +110,21 @@ export interface WorkerOpts {
    * would be a path that fails to open rather than an absence.
    */
   onSessionFile?: (path: string) => void;
+  /**
+   * Installs the run's operator pause controller the moment the session
+   * exists; absent = no pause surface (tests, one-shot callers).
+   */
+  onPauseControl?: (control: WorkerPauseControl) => 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.
+ * Session creation plus the clock seam needed to prove wall-clock behavior
+ * without sleeping. Production callers use the defaults.
  */
 export interface RunWorkerDeps {
   createSession: typeof createSession;
+  now?: () => number;
+  schedule?: (callback: () => void, delayMs: number) => () => void;
 }
 
 export interface WorkerResult {
@@ -160,6 +192,19 @@ export function deriveResult(report: string): {
   };
 }
 
+/**
+ * Did this report state a verdict at all?
+ *
+ * The discriminator between "the worker said something about its outcome" and
+ * "the worker said something else entirely". A finished worker woken by its own
+ * stale polling timers emits neither `state: pushed-green` nor `state: blocked`
+ * — it emits prose — and that is the only case where an earlier verdict is
+ * still the run's real answer.
+ */
+export function hasVerdictLine(report: string): boolean {
+  return STATE_LINE_PATTERN.test(report);
+}
+
 /**
  * Is this `agent_end` the end of the run?
  *
@@ -187,6 +232,8 @@ export async function runWorker(
 ): Promise<WorkerResult> {
   const { workerWallClockMs } = o.caps;
   const maxTurns = o.maxTurns ?? (() => o.caps.workerMaxTurns);
+  const now = deps.now ?? Date.now;
+  const schedule = deps.schedule ?? scheduleWallClock;
 
   const session = await deps.createSession({
     cwd: o.cwd,
@@ -224,19 +271,41 @@ export async function runWorker(
   let turns = 0;
   let spendUsd = 0;
   let report = "";
+  // The newest COMPLETE `pushed-green` verdict this session emitted. Tracked
+  // apart from `report` because `report` is deliberately the newest non-empty
+  // text — a run cut off mid-sentence must still report what it said last —
+  // and a worker that finishes, then wakes on its own stale polling timers,
+  // overwrites its own verdict with "nothing to resume" chatter. veltro#406
+  // burned 180/180 turns that way and charged an attempt against a PR that
+  // merged (#217).
+  let claim: { prUrl: string; headSha: string } | undefined;
   let killedBy: KilledBy | undefined;
-  // Bun's global timer handle; cleared on every exit path below.
-  let timer: Timer | undefined;
+  // Canceler for the armed wall clock; invoked on every exit path below.
+  let cancelWallClock: (() => void) | undefined;
+  let wallClockRemainingMs = workerWallClockMs;
+  let wallClockArmedAt = now();
+  let pausePhase: WorkerPausePhase = "running";
+  let resumeWaiter: PromiseWithResolvers<string> | undefined;
+  // A terminal agent_end or cap has settled the run.
+  let done = false;
   // 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>();
+  // Resolves whenever a pause request must interrupt the existing
+  // non-terminal agent_end wait. Re-armed after its resume prompt is consumed.
+  let pauseRequested = 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;
+    if (cancelWallClock === undefined) return;
+    cancelWallClock();
+    cancelWallClock = undefined;
+  };
+
+  const armWallClock = () => {
+    wallClockArmedAt = now();
+    cancelWallClock = schedule(() => kill("wallclock"), wallClockRemainingMs);
   };
 
   const kill = (by: KilledBy) => {
@@ -247,9 +316,80 @@ export async function runWorker(
     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.
+    done = true;
     settle();
   };
 
+  const takeResumePrompt = async (): Promise<string | undefined> => {
+    const waiter = resumeWaiter;
+    if (waiter === undefined) return undefined;
+    const prompt = await Promise.race([
+      waiter.promise,
+      settled.then(() => undefined),
+    ]);
+    if (resumeWaiter === waiter) {
+      resumeWaiter = undefined;
+      pauseRequested = Promise.withResolvers<void>();
+    }
+    return killedBy !== undefined || done ? undefined : prompt;
+  };
+
+  o.onPauseControl?.({
+    phase: () => pausePhase,
+    pause: async () => {
+      if (killedBy !== undefined || done) {
+        throw new Error("the run is settling; nothing left to pause");
+      }
+      if (pausePhase !== "running") throw new Error(`the worker is already ${pausePhase}`);
+      if (resumeWaiter !== undefined) {
+        throw new Error("the worker resume is still starting");
+      }
+      pausePhase = "pausing";
+      resumeWaiter = Promise.withResolvers<string>();
+      pauseRequested.resolve();
+      // Bank the remaining wall clock before the abort: a slow drain must not
+      // be cap-killed mid-park (#238 acceptance 3).
+      wallClockRemainingMs = Math.max(
+        1_000,
+        wallClockRemainingMs - (now() - wallClockArmedAt),
+      );
+      clearWallClock();
+      try {
+        await session.park();
+      } catch (err) {
+        pausePhase = "running";
+        if (killedBy !== undefined || done) {
+          resumeWaiter = undefined;
+          throw err;
+        }
+        // The abort may already have unwound prompt() even though park itself
+        // failed. Wake that path with the same defensive continuation rather
+        // than leaving the worker hung on an orphaned waiter.
+        armWallClock();
+        resumeWaiter?.resolve(RESUME_PROMPT);
+        throw err;
+      }
+      if (killedBy !== undefined || done) {
+        pausePhase = "running";
+        resumeWaiter = undefined;
+        throw new Error("the run settled while pausing");
+      }
+      pausePhase = "paused";
+    },
+    resume: () => {
+      if (pausePhase !== "paused") {
+        throw new Error(
+          pausePhase === "pausing"
+            ? "still pausing — wait until it reports paused"
+            : "the worker is not paused",
+        );
+      }
+      pausePhase = "running";
+      armWallClock();
+      resumeWaiter?.resolve(RESUME_PROMPT);
+    },
+  });
+
   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
@@ -265,7 +405,13 @@ export async function runWorker(
     // 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;
+    if (text !== "") {
+      report = text;
+      const stated = deriveResult(text);
+      if (stated.state === "pushed-green" && stated.prUrl !== undefined && stated.headSha !== undefined) {
+        claim = { prUrl: stated.prUrl, headSha: stated.headSha };
+      }
+    }
 
     // Real cost lives on assistant messages as `usage.cost.total` (live hermes
     // transcripts, 2026-08-07). The earlier agent_end.telemetry path never
@@ -296,6 +442,8 @@ export async function runWorker(
     // all — is a finished run.
     const isTerminal = field(event, "isTerminal");
     if (shouldComplete(typeof isTerminal === "boolean" ? { isTerminal } : {})) {
+      if (pausePhase !== "running") return;
+      done = true;
       settle();
       return;
     }
@@ -306,14 +454,33 @@ export async function runWorker(
   // 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);
+  armWallClock();
 
   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;
+    let next: string | undefined = o.brief;
+    while (next !== undefined) {
+      try {
+        await session.prompt(next);
+      } catch (cause) {
+        // Our own abort surfaces here on some paths: a cap kill (existing
+        // behavior) or an operator park (new). Anything else is a real failure.
+        if (killedBy === undefined && resumeWaiter === undefined) throw cause;
+      }
+      next = undefined;
+      if (killedBy !== undefined) break;
+      if (resumeWaiter === undefined && resuming && !done) {
+        // A non-terminal agent_end ordinarily waits for the harness to finish
+        // later. A pause request must wake that wait so resume can prompt the
+        // same session instead of hanging behind the old settlement promise.
+        await Promise.race([settled, pauseRequested.promise]);
+      }
+      if (killedBy !== undefined) break;
+      if (resumeWaiter !== undefined) {
+        next = await takeResumePrompt();
+        if (next === undefined) break;
+        continue;
+      }
+    }
   } catch (cause) {
     // Our own abort surfaces here on some paths; that is a kill, not a crash.
     if (killedBy === undefined) {
@@ -326,6 +493,7 @@ export async function runWorker(
       });
     }
   } finally {
+    done = true;
     // 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();
@@ -337,9 +505,26 @@ export async function runWorker(
   }
 
   if (killedBy !== undefined) {
-    return withSessionFacts({ state: "killed", turns, spendUsd, report, killedBy });
+    // The PR and head are facts the session already established, so they
+    // survive the kill. Without them `shouldContinueAfterTurnsCap` sees no
+    // artifacts and charges an implementation attempt for a cap kill that had
+    // real work to continue from.
+    return withSessionFacts({
+      state: "killed",
+      turns,
+      spendUsd,
+      report,
+      killedBy,
+      ...(claim === undefined ? {} : { prUrl: claim.prUrl, headSha: claim.headSha }),
+    });
   }
 
+  // An explicit later verdict always wins: a worker that pushed green and then
+  // stopped to ask a question means the question. The earlier claim is only
+  // restored when the last thing said was not a verdict at all.
+  if (claim !== undefined && !hasVerdictLine(report)) {
+    return withSessionFacts({ state: "pushed-green", ...claim, turns, spendUsd, report });
+  }
   return withSessionFacts({
     ...deriveResult(report),
     turns,