@opsee/cli 0.11.9

package/src/foreman/core/triage.ts

@@ -0,0 +1,138 @@
+/**
+ * The Triage turn (see ../../../CONTEXT.md, spec story 23): a short unattended turn the Foreman runs
+ * on a Ready Task whose work contract has a Goal and Acceptance Criteria but no Verification
+ * section, to draft one before dispatching. The Foreman drafts rather than blocks, so a legacy Task
+ * does not stall the fleet and the gap stays visible as a comment on the Task.
+ *
+ * The turn goes through the same Worker Adapter as any other, in the Task's Workspace so the Worker
+ * can read the repository for the real commands, with a small turn cap. Its Completion Report
+ * carries the draft in `summary` (triage-draft.ts says why). This module builds the prompt and
+ * drains the turn; run.ts records the outcome, since the Run Record write is the commit (ADR-0009).
+ */
+import type { Account } from "../account.js";
+import type { TrackerTask } from "../tracker-adapter.js";
+import type { AdapterEvent, WorkerAdapter } from "../worker-adapter.js";
+import { tail } from "./install.js";
+import type { WorkContract } from "./work-contract.js";
+
+/** Reading a few files and writing one section needs a handful of agentic turns, not a Worker's
+ * budget; the Run's own `maxTurns` lowers this, never raises it. */
+export const TRIAGE_MAX_TURNS = 10;
+
+/**
+ * What a Triage turn's attempt-event summary starts with, so a reader can tell it from the
+ * implementer turn that carries the same attempt number.
+ *
+ * The Triage turn runs *before* the dispatch event that fixes the implementer's number, so it is
+ * given the number the implementer is about to take (`attempt = priorDispatches + 1`, run.ts) —
+ * several other components match on that numbering (the readiness report, the Verifier's
+ * attribution, the Defect dedup, `foreman review`), so the implementer's number is what must stay
+ * intact. That leaves one attempt number carrying two attempt events, triage first, and the two
+ * places that settle by number (`settledOutcome` in core/reconcile.ts, `finishSettlement` in
+ * core/run.ts) both take the *first* match. Reading the triage turn's success as the implementer
+ * attempt's settlement drops a live row and blocks a Task whose Worker was still running — exactly
+ * what Reconcile exists to prevent. So the triage event is tagged, and those two skip it.
+ *
+ * `retryableFailuresOf` deliberately does *not* skip it: a Triage turn that hit a rate limit is a
+ * turn the vendor refused, and it spends the retry cap like any other.
+ */
+export const TRIAGE_MARKER = "[triage]";
+
+/** Whether an attempt event's summary is a Triage turn's rather than an implementer turn's. */
+export function isTriageSummary(summary: string): boolean {
+  return summary.startsWith(TRIAGE_MARKER);
+}
+
+export function triagePrompt(task: Pick<TrackerTask, "identifier" | "title">, contract: WorkContract, workspace: { path: string }): string {
+  return [
+    `You are a Worker run unattended by the Foreman for a Triage turn on Task ${task.identifier}: ${task.title}.`,
+    "",
+    "The Task's work contract has a Goal and Acceptance Criteria but no Verification section. Draft that section.",
+    `Do not implement the Task and do not change any file: your working directory ${workspace.path} is the repository, read it to find the real commands and, if the Task touches a UI, the real routes.`,
+    "",
+    `## Goal\n\n${contract.sections.Goal ?? "(none)"}`,
+    "",
+    `## Acceptance Criteria\n\n${contract.sections["Acceptance Criteria"] ?? "(none)"}`,
+    "",
+    "## What to draft",
+    "",
+    "A Verification section: how a Verifier who never sees the implementer's transcript proves the work from the outside.",
+    "Give the exact commands to run (tests, lint, typecheck, build, whatever this repository uses) and, for anything with a UI,",
+    "the user journey to exercise in a browser: how to start the app, which pages to open, what to do there, and what must be visible.",
+    "Write it as markdown with no heading line, in the repository's own vocabulary, concrete enough to follow without asking.",
+    "",
+    "## Finishing",
+    "",
+    "End the turn with a Completion Report: outcome `done`, and the drafted Verification section verbatim as the summary",
+    "(nothing else in the summary); leave decisions, tried, blockers and proposedLearnings empty. Report `blocked`, with the",
+    "reason as a blocker, only if the Goal and Acceptance Criteria are too thin to draft from.",
+  ].join("\n");
+}
+
+export interface TriageTurnRequest {
+  worker: WorkerAdapter;
+  account: Account;
+  task: Pick<TrackerTask, "identifier" | "title">;
+  contract: WorkContract;
+  workspace: { path: string };
+  maxTurns?: number;
+  stallTimeoutMs?: number;
+  log: (line: string) => void;
+  now: () => number;
+}
+
+export interface DrainedTurn {
+  terminal: Extract<AdapterEvent, { type: "completed" | "failed" }>;
+  durationMs: number;
+  outputTail: string;
+  /** The vendor's rate-limit report, when one came (story 30). A Triage turn is a turn on the
+   * Account like any other, so a limit it hit Pauses the Account; the terminal event alone does not
+   * carry the reset the vendor named, which is what decides how long. */
+  rateLimit?: { resetAt?: string; message: string };
+}
+
+/** Runs one Triage turn to its terminal event, logging progress the way the dispatch loop does. */
+export async function driveTriageTurn(req: TriageTurnRequest): Promise<DrainedTurn> {
+  const maxTurns = Math.min(TRIAGE_MAX_TURNS, req.maxTurns ?? TRIAGE_MAX_TURNS);
+  const started = req.now();
+  const handle = req.worker.launch({
+    account: req.account,
+    cwd: req.workspace.path,
+    prompt: triagePrompt(req.task, req.contract, req.workspace),
+    maxTurns,
+    stallTimeoutMs: req.stallTimeoutMs,
+  });
+  req.log(`triage: ${req.account.vendor} turn on ${req.task.identifier} in ${req.workspace.path} (at most ${maxTurns} turns)`);
+  const output: string[] = [];
+  let terminal: DrainedTurn["terminal"] | undefined;
+  let rateLimit: DrainedTurn["rateLimit"];
+  for await (const event of handle.events) {
+    switch (event.type) {
+      case "started":
+        req.log(`triage: session ${event.sessionId}`);
+        break;
+      case "output":
+        for (const line of event.text.split("\n")) {
+          output.push(line);
+          req.log(`  | ${line}`);
+        }
+        break;
+      case "tool":
+        req.log(`  tool ${event.name}`);
+        break;
+      case "rate_limited":
+        rateLimit = { resetAt: event.resetAt, message: event.message };
+        req.log(`triage: rate limited: ${event.message}${event.resetAt ? ` (resets ${event.resetAt})` : ""}`);
+        break;
+      case "stalled":
+        req.log(`triage: stalled, no output for ${event.silentMs}ms`);
+        break;
+      case "completed":
+      case "failed":
+        terminal = event;
+        break;
+    }
+  }
+  if (!terminal) throw new Error("Worker Adapter contract violated: the event stream ended without a terminal event");
+  return { terminal, durationMs: req.now() - started, outputTail: tail(output.join("\n")), rateLimit };
+}