omp-conductor 0.18.2 → 0.19.0

package/src/dashboard/controls.ts

@@ -0,0 +1,336 @@
+/**
+ * The dashboard's mutating surface (epic #292, slice 3/5 — #295).
+ *
+ * Slices 1/5 and 2/5 made the fleet legible from a browser; this one makes it
+ * drivable, so an operator can pause dispatch, extend a run, unblock an issue,
+ * control a live worker and answer a decision without a shell on the host.
+ *
+ * ## One rule, and everything here follows from it
+ *
+ * **No parallel implementations.** Every action routes to the exact code its CLI
+ * twin runs, and where that code already lives behind an HTTP endpoint the
+ * dashboard *calls that endpoint* rather than reaching past it to the store.
+ *
+ * That second half is the part worth stating, because the naive reading goes the
+ * other way. `extend` ultimately calls `store.setTurnOverride`, so it is tempting
+ * to call that from here. But `turnLimitResponse` is not a thin wrapper around it:
+ * it owns a whole validation ladder — the `workerMaxTurnsCeiling` bound, the
+ * live-controller check against the run's stored state, the "already has a higher
+ * ceiling" refusal, the live-registry extend that takes effect *this* turn versus
+ * the next-attempt override that does not. Reimplementing that here would be
+ * exactly the fork the slice forbids, and the copy nobody updated would be the
+ * one the browser used. So `extend` is proxied, like worker control.
+ *
+ * What is called directly is what has no HTTP owner: the pause sentinel and the
+ * tick marker are host-local files, and `unblock` and decision resolution are
+ * store operations the CLI performs in-process too.
+ *
+ * ## Attribution
+ *
+ * Every mutation records itself the way its CLI twin does, with source
+ * `"dashboard"` where the sink takes a source. That is what makes
+ * `omp-conductor status` able to say *who* paused the fleet, rather than only
+ * that it is paused.
+ *
+ * ## What is deliberately absent
+ *
+ * `arm`. It requires an inbound Telegram proof that a human answered a
+ * challenge, and a browser button cannot supply one. A dashboard `arm` would
+ * either weaken that proof or lie about having it, so arming stays CLI/Telegram
+ * exactly as the epic says.
+ */
+
+import { disarmTicks, hold, releaseHold } from "../fleet.ts";
+import { healthCheck, livingDaemon } from "../lifecycle.ts";
+import { unblockIssue } from "../unblock.ts";
+import { makeTracker } from "../tracker/github.ts";
+import { dbPath, openStore } from "../store.ts";
+import { loadConfig, resolveCaps } from "../config.ts";
+import type { ProjectConfig } from "../types.ts";
+
+/** The source string every dashboard mutation attributes itself with. */
+/**
+ * The source token every dashboard mutation attributes itself with.
+ *
+ * A single word by contract: the pause fence matches on `source=` and whitespace
+ * there produces a pause it cannot prove (#552, `pauseSourceToken`). The
+ * operator's sentence rides in `reason=` instead.
+ */
+export const DASHBOARD_SOURCE = "dashboard";
+
+/** A mutation's outcome, already shaped as the HTTP answer it becomes. */
+export interface ControlOutcome {
+  status: number;
+  body: unknown;
+}
+
+/** Injected so tests drive every branch without a daemon, a tracker or a clock. */
+export interface ControlDeps {
+  /** The project this action names, already resolved by the router. */
+  project: ProjectConfig;
+  hold?: typeof hold;
+  releaseHold?: typeof releaseHold;
+  disarmTicks?: typeof disarmTicks;
+  /**
+   * Forwards one request to the owning daemon's own HTTP surface. Returns
+   * `undefined` when no living daemon serves this project — a 502 the caller
+   * words, never a silent success.
+   */
+  proxy?: (
+    project: ProjectConfig,
+    path: string,
+    body: unknown,
+  ) => Promise<{ status: number; body: unknown } | undefined>;
+  /** `unblockIssue` with the CLI's own tracker/store/caps wiring. */
+  unblock?: (
+    project: ProjectConfig,
+    issue: number,
+    opts: { force?: boolean },
+  ) => Promise<{ status: number; body: unknown }>;
+  /** Resolves one decision row; `false` when it changed nothing. */
+  answerDecision?: (id: string, answer: string) => boolean;
+  now?: () => number;
+}
+
+/** The reason string a pause/hold takes, validated once for every caller. */
+function readReason(body: unknown): string | undefined {
+  if (body === null || typeof body !== "object") return undefined;
+  const reason = Reflect.get(body, "reason");
+  return typeof reason === "string" && reason.trim() !== "" ? reason.trim() : undefined;
+}
+
+/**
+ * Stop new claims, keeping the heartbeat.
+ *
+ * `keepTicks` is the whole reason this is `hold(..., { keepTicks: true })` and
+ * not a bare `hold`: disarming is the expensive half, because re-arming needs a
+ * Telegram challenge an operator has to answer in the chat. A browser button
+ * that cost a manual round trip to undo would not be used, so the dashboard's
+ * pause is the cheap, reversible one — `resume` alone restores the fleet.
+ */
+export function dashboardPause(body: unknown, d: ControlDeps): ControlOutcome {
+  const reason = readReason(body);
+  if (reason === undefined) {
+    return { status: 400, body: { error: "reason must be a non-empty string" } };
+  }
+  const held = (d.hold ?? hold)(d.project.name, DASHBOARD_SOURCE, { keepTicks: true, reason });
+  return { status: 200, body: { paused: true, wasPaused: held.wasPaused, source: DASHBOARD_SOURCE } };
+}
+
+/** Clear the pause. Idempotent, exactly as `resume` is on the CLI. */
+export function dashboardResume(d: ControlDeps): ControlOutcome {
+  (d.releaseHold ?? releaseHold)(d.project.name);
+  return { status: 200, body: { paused: false } };
+}
+
+/**
+ * The heavier hold: stop claims *and* disarm the heartbeat.
+ *
+ * Distinct from `pause` on purpose — this is the one that costs a Telegram
+ * challenge to undo — so the two are separate endpoints and the UI can warn
+ * about this one and not the other.
+ */
+export function dashboardHold(body: unknown, d: ControlDeps): ControlOutcome {
+  const reason = readReason(body);
+  if (reason === undefined) {
+    return { status: 400, body: { error: "reason must be a non-empty string" } };
+  }
+  const held = (d.hold ?? hold)(d.project.name, DASHBOARD_SOURCE, { reason });
+  return {
+    status: 200,
+    body: {
+      paused: true,
+      wasPaused: held.wasPaused,
+      disarmed: held.disarmed?.wasArmed ?? false,
+      source: DASHBOARD_SOURCE,
+    },
+  };
+}
+
+/** Disarm ticks without touching dispatch. */
+export function dashboardDisarm(d: ControlDeps): ControlOutcome {
+  const result = (d.disarmTicks ?? disarmTicks)(d.project.name);
+  return { status: 200, body: { armed: false, wasArmed: result.wasArmed, path: result.path } };
+}
+
+/**
+ * Raise one run's turn budget, through the daemon that owns it.
+ *
+ * Proxied rather than written directly: see this module's header. The daemon's
+ * `PUT /runs/:issue/turn-limit` owns every bound and refusal, and its answers —
+ * 409 for a settled run, 422 over the ceiling — pass through unchanged, so the
+ * browser and `omp-conductor extend` cannot come to disagree about what is
+ * allowed.
+ */
+export async function dashboardExtend(
+  issue: number,
+  body: unknown,
+  d: ControlDeps,
+): Promise<ControlOutcome> {
+  const maxTurns = body === null || typeof body !== "object" ? undefined : Reflect.get(body, "maxTurns");
+  if (!Number.isSafeInteger(maxTurns) || (maxTurns as number) < 1) {
+    return { status: 400, body: { error: "maxTurns must be a positive integer" } };
+  }
+  return proxied(d, `/runs/${issue}/turn-limit`, {
+    project: d.project.name,
+    maxTurns: maxTurns as number,
+  });
+}
+
+/**
+ * Pause, resume or stop one live worker, through the daemon that owns it.
+ *
+ * The daemon holds the session controller; nothing else can reach it. A dead
+ * daemon is a 502 naming it, never a 200 that pretends a worker was paused.
+ */
+export async function dashboardWorkerControl(
+  issue: number,
+  action: "pause" | "resume" | "stop",
+  body: unknown,
+  d: ControlDeps,
+): Promise<ControlOutcome> {
+  const payload: Record<string, unknown> = { project: d.project.name };
+  if (action === "stop") {
+    const reason = readReason(body);
+    if (reason === undefined) {
+      // The CLI requires a reason to stop a run, because a terminal settlement
+      // with no recorded why is unauditable. A button must not be cheaper.
+      return { status: 400, body: { error: "reason must be a non-empty string" } };
+    }
+    payload["reason"] = `${DASHBOARD_SOURCE}: ${reason}`;
+  }
+  return proxied(d, `/runs/${issue}/${action}`, payload);
+}
+
+/** One proxied call, with the daemon-down answer worded once. */
+async function proxied(d: ControlDeps, path: string, body: unknown): Promise<ControlOutcome> {
+  const forward = d.proxy ?? defaultProxy;
+  const answer = await forward(d.project, path, body);
+  if (answer === undefined) {
+    return {
+      status: 502,
+      body: {
+        error:
+          `no living daemon serves project "${d.project.name}", so ${path} could not be applied. ` +
+          "Start it with `omp-conductor start` and try again.",
+      },
+    };
+  }
+  return { status: answer.status, body: answer.body };
+}
+
+/**
+ * Take an issue out of a blocked/failed state, exactly as `omp-conductor
+ * unblock` does — same tracker, same store, same caps, same refusals.
+ *
+ * `force` is accepted and passed through, but the UI is required to confirm it
+ * by name: it records that a human inspected a worktree whose uncommitted work
+ * is the only copy, and a button that did that silently would destroy work
+ * nobody chose to lose.
+ */
+export async function dashboardUnblock(
+  issue: number,
+  body: unknown,
+  d: ControlDeps,
+): Promise<ControlOutcome> {
+  const force = body !== null && typeof body === "object" && Reflect.get(body, "force") === true;
+  const run = d.unblock ?? defaultUnblock;
+  return run(d.project, issue, { force });
+}
+
+/**
+ * Answer one open decision row.
+ *
+ * `resolveDecision` returns false when it changed no rows, which is exactly the
+ * already-answered case — so a second answer is a 409 rather than a silent
+ * overwrite of the first. That matters more than it looks: the row is the record
+ * of what a human decided, and a later write would rewrite history.
+ */
+export function dashboardAnswerDecision(id: string, body: unknown, d: ControlDeps): ControlOutcome {
+  const answer = body === null || typeof body !== "object" ? undefined : Reflect.get(body, "answer");
+  if (typeof answer !== "string" || answer.trim() === "") {
+    return { status: 400, body: { error: "answer must be a non-empty string" } };
+  }
+  const resolve = d.answerDecision ?? defaultAnswerDecision;
+  return resolve(id, answer.trim())
+    ? { status: 200, body: { id, state: "answered", resolution: answer.trim() } }
+    : {
+        status: 409,
+        body: { error: `decision ${id} is not open — it was already answered or withdrawn` },
+      };
+}
+
+// ------------------------------------------------------- production wiring --
+
+/** Forward to the living daemon's own HTTP surface, or report there is none. */
+async function defaultProxy(
+  project: ProjectConfig,
+  path: string,
+  body: unknown,
+): Promise<{ status: number; body: unknown } | undefined> {
+  const record = livingDaemon();
+  // The same membership rule every other dashboard read uses (#379): a record
+  // pinned to another project does not serve this one, and forwarding to it
+  // would apply an operator's action to the wrong fleet.
+  if (record === undefined) return undefined;
+  if (record.project !== undefined && record.project !== project.name) return undefined;
+  // Cheap liveness first, so an unreachable daemon is a 502 rather than a
+  // mutation attempt that hangs the browser.
+  if (!(await healthCheck(record.port)).ok) return undefined;
+  try {
+    const res = await fetch(`http://127.0.0.1:${record.port}${path}`, {
+      method: "PUT",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(10_000),
+    });
+    const text = await res.text();
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(text) as unknown;
+    } catch {
+      parsed = { error: text.trim() };
+    }
+    return { status: res.status, body: parsed };
+  } catch {
+    return undefined;
+  }
+}
+
+/** `unblockIssue` with the CLI's own wiring, translated to an HTTP answer. */
+async function defaultUnblock(
+  project: ProjectConfig,
+  issue: number,
+  opts: { force?: boolean },
+): Promise<{ status: number; body: unknown }> {
+  const store = openStore(dbPath());
+  try {
+    const cfg = loadConfig();
+    const outcome = await unblockIssue(
+      project,
+      makeTracker(project),
+      store,
+      issue,
+      opts,
+      resolveCaps(project, cfg.defaults),
+    );
+    // A refusal is the store's own verdict — an uncommitted worktree that is the
+    // only copy of a worker's output — and it is a 409, not a 500: nothing went
+    // wrong, the answer is no.
+    return outcome.refused === undefined
+      ? { status: 200, body: outcome }
+      : { status: 409, body: outcome };
+  } finally {
+    store.close();
+  }
+}
+
+/** Resolve one decision through the same store call `decision resolve` uses. */
+function defaultAnswerDecision(id: string, answer: string): boolean {
+  const store = openStore(dbPath());
+  try {
+    return store.resolveDecision(id, "answered", answer, Date.now());
+  } finally {
+    store.close();
+  }
+}

package/src/dashboard/index.html

@@ -35,18 +35,48 @@
     <h2 id="project-title"></h2>
     <p id="project-daemon" class="state"></p>
     <div id="project-summary" class="summary"></div>
+    <!-- The control surface (#295). `arm` is deliberately absent: it needs an
+         inbound Telegram proof a browser cannot supply, so it stays CLI. -->
+    <div class="controls" id="controls">
+      <button data-control="pause" type="button">Pause dispatch</button>
+      <button data-control="resume" type="button">Resume</button>
+      <button data-control="hold" type="button" class="destructive">Hold (disarms ticks)</button>
+      <button data-control="disarm" type="button" class="destructive">Disarm ticks</button>
+      <p id="control-result" class="state" hidden></p>
+    </div>
     <nav class="tabs" id="tabs">
       <button data-tab="board" type="button">Board</button>
       <button data-tab="ledger" type="button">Ledger</button>
       <button data-tab="reports" type="button">Reports</button>
+      <button data-tab="stats" type="button">Analytics</button>
     </nav>
     <section id="panel-board"></section>
     <section id="panel-ledger" hidden></section>
     <section id="panel-reports" hidden></section>
+    <section id="panel-stats" hidden>
+      <!-- Analytics (#297). The window selector mirrors `stats --since`, and the
+           numbers are the same aggregation `stats --json` prints. -->
+      <div class="controls" id="stats-window">
+        <button data-since="7d" type="button">7 days</button>
+        <button data-since="30d" type="button">30 days</button>
+        <button data-since="custom" type="button">Custom…</button>
+        <span id="stats-window-label" class="state"></span>
+      </div>
+      <div id="stats-body"></div>
+    </section>
 
     <div id="run-detail" hidden>
       <p class="back"><a href="#" id="back-to-board">← board</a></p>
       <h3 id="run-title"></h3>
+      <div class="controls" id="run-controls"></div>
+      <!-- Live transcript (#296): the same lines `omp-conductor tail` prints,
+           streamed as SSE. Autoscroll is on until the operator scrolls up. -->
+      <div class="transcript-head">
+        <button id="transcript-toggle" type="button">Watch transcript</button>
+        <label><input type="checkbox" id="transcript-autoscroll" checked /> autoscroll</label>
+        <span id="transcript-state" class="state"></span>
+      </div>
+      <pre id="transcript" class="transcript" hidden></pre>
       <table class="runs">
         <thead>
           <tr><th>Attempt</th><th>State</th><th>Spend</th><th>Failure class</th><th>PR</th><th>Started</th></tr>