makersclaw 0.7.0 → 0.8.1

package/templates/next/files/lib/automations.js

@@ -0,0 +1,660 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { clawUrl } from "./claw";
+
+// The automations engine, from an app's own page (0.8.1, D26, Phase 6.2):
+// the doors under `_claw/automations…` and the hooks the automation blocks
+// draw. An app lists its own automations, opens one, edits and saves it,
+// keeps a version, switches it on and runs it, and reads a run step by
+// step, all inside the app, in the app's theme. The platform decides who
+// may do what (any member edits and runs, until roles); a hidden button is
+// never the guard.
+//
+//   useAutomations()        the list, the switch, a new one, the starting points the platform
+//                           keeps, and "Describe it" (an automation drafted from a sentence)
+//   useAutomation(id)       one: its versions and runs; save, keep, go live, test (a dry run:
+//                           it reads real data and changes nothing)
+//   useAutomationRun(runId) one run, followed while it goes
+//
+// Every call resolves { ok: true, status, data } or { ok: false, status,
+// error, code?, problems?, unavailable } and never throws. `problems` is
+// the platform's list of what is wrong with a definition it refused (one
+// plain line each); `unavailable: true` (a claw from before the engine, or
+// no gateway) is a quiet "not set up yet", never an error. The hooks poll
+// only while the page is shown, back off while the door is missing, and
+// abort on unmount, as the other kit hooks do (lib/hooks.js).
+//
+// Re-exported from lib/hooks.js, so a surface imports them from there.
+
+const BACKOFF_MS = 60000;
+/** How often a list or one automation looks again while it is idle. */
+const IDLE_MS = 30000;
+/** ...and while a run is going. */
+const RUNNING_MS = 5000;
+/** One run, followed. */
+const RUN_FOLLOW_MS = 2500;
+/** A run still going or waiting on its owner. */
+const ACTIVE = new Set(["queued", "running", "waiting", "needs_you"]);
+
+const listOf = (v) => (Array.isArray(v) ? v : []);
+const segment = (id) => {
+  const text = typeof id === "string" || typeof id === "number" ? String(id).trim() : "";
+  return text ? encodeURIComponent(text) : null;
+};
+const noId = (what) => Promise.resolve({ ok: false, status: 0, error: `no ${what} to ask about`, unavailable: false });
+
+/* ---- the doors ------------------------------------------------------------ */
+
+/** One call to a _claw route. Like lib/claw.js's claw(), but a refusal keeps
+ *  its `problems`: the lines the editor shows against the steps. */
+async function call(path, { method = "GET", body, signal } = {}) {
+  let res;
+  try {
+    res = await fetch(clawUrl(path), {
+      method,
+      credentials: "same-origin",
+      cache: "no-store",
+      headers: { accept: "application/json", ...(body !== undefined ? { "content-type": "application/json" } : {}) },
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+      signal,
+    });
+  } catch (error) {
+    if (error?.name === "AbortError") return { ok: false, status: 0, error: "aborted", aborted: true };
+    return { ok: false, status: 0, error: "not reachable", unavailable: true };
+  }
+  const text = await res.text().catch(() => "");
+  let parsed = null;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    /* not JSON: the words are the text */
+  }
+  if (res.ok) return { ok: true, status: res.status, data: parsed ?? (text || null) };
+  const failure = parsed && typeof parsed === "object" ? parsed : {};
+  const error = failure.error || failure.message || text || res.statusText || `HTTP ${res.status}`;
+  const code = typeof failure.code === "string" && failure.code ? failure.code : undefined;
+  // A 404 with no code is a gateway with no such route (a claw from before
+  // the engine); with one it is the route refusing ("not_found").
+  if (res.status === 404 && !code) return { ok: false, status: 404, error: "not available yet", unavailable: true };
+  const problems = Array.isArray(failure.problems) ? failure.problems.filter((p) => typeof p === "string") : undefined;
+  // A refusal that asks something back ("Describe it" needs an answer) keeps its questions.
+  const questions = Array.isArray(failure.questions) ? failure.questions.filter((q) => typeof q === "string" && q.trim()) : undefined;
+  // A `changed` refusal says which version is the newest (`latest`).
+  const latest = Number.isInteger(failure.latest) ? failure.latest : undefined;
+  return { ok: false, status: res.status, error, ...(code ? { code } : {}), ...(latest !== undefined ? { latest } : {}), ...(problems ? { problems } : {}), ...(questions ? { questions } : {}), unavailable: false };
+}
+
+/** GET _claw/automations → { automations: [{ id, key, name, status, live_version,
+ *  draft_version, next_run_at, tz, trigger, last_run, active_runs, source, edited … }] }:
+ *  this app's automations. */
+export function automations({ signal } = {}) {
+  return call("automations", { signal });
+}
+
+/** GET _claw/automations/<id> → { automation, live, draft, versions, estimate,
+ *  estimate_draft }: one, with the version that runs, the draft ahead of it
+ *  and what a run is expected to cost. */
+export function automation(id, { signal } = {}) {
+  const which = segment(id);
+  return which ? call(`automations/${which}`, { signal }) : noId("automation");
+}
+
+/** POST _claw/automations { definition, note?, go_live? } → { id, version, status }:
+ *  a new automation, as a draft. A refusal carries `problems`. */
+export function createAutomation(body) {
+  return call("automations", { method: "POST", body });
+}
+
+/** PATCH _claw/automations/<id>: { definition, expect_version?, note? } saves a draft
+ *  version; { keep: true } makes the draft the version that runs; { status: "on" | "off" }
+ *  is the Live switch. `keep` and `status: "on"` are refused with `needs_test` until a test of
+ *  that version passed; `skip_test: true` on the same body is the member's own, deliberate
+ *  override (an agent never sends it). A refusal carries its `code` (`invalid_automation`,
+ *  `changed`, `no_live`, `needs_test`…) and, for a definition, `problems`. */
+export function saveAutomation(id, body) {
+  const which = segment(id);
+  return which ? call(`automations/${which}`, { method: "PATCH", body }) : noId("automation");
+}
+
+/** POST _claw/automations/<id>/run { inputs?, version?, dry?, sample? } → { run_id, test, dry,
+ *  version }: one run, on the member's press. `dry: true` is a TEST: it reads real data and
+ *  changes nothing (a version that is not the live one always runs as a test); `sample` is a
+ *  pretend trigger payload. Say its price on the control (the automation's `estimate`). */
+export function runAutomation(id, body = {}) {
+  const which = segment(id);
+  return which ? call(`automations/${which}/run`, { method: "POST", body }) : noId("automation");
+}
+
+/** GET _claw/automations/<id>/runs → { runs: [{ id, status, trigger_type, is_test,
+ *  created_at, started_at, ended_at, credits, error }] }, newest first. */
+export function automationRuns(id, { limit, signal } = {}) {
+  const which = segment(id);
+  if (!which) return noId("automation");
+  const n = Number.isInteger(limit) && limit >= 1 ? `?limit=${limit}` : "";
+  return call(`automations/${which}/runs${n}`, { signal });
+}
+
+/** GET _claw/automation-runs/<id> → { run, automation, steps: [{ path, step_id, kind,
+ *  attempt, status, credits, error, input?, output?, fix? }], steps_visible }: one run
+ *  with its steps. A step's data is for those who may read it (`steps_visible`). */
+export function automationRun(runId, { signal } = {}) {
+  const which = segment(runId);
+  return which ? call(`automation-runs/${which}`, { signal }) : noId("run");
+}
+
+/** POST _claw/automation-runs/<id>/control { op, path?, input?, confirm_not_sent?,
+ *  raise_cap_by?, confirm_resend? } → { run_id, status, paused, path? }: the controls of a
+ *  run. `op`: pause · resume · stop · retry · skip · edit · retry_from (start over at a
+ *  top-level step, running it and every step after it again, on a finished or parked run).
+ *  A refusal's `code` is `not_found` · `not_active` · `not_blocked` · `running` ·
+ *  `needs_confirm` · `unknown_step` · `output_needed` · `bad_request` · `bad_step` · `busy` ·
+ *  `not_controllable` · `needs_confirm_resend` (a step from there on already sent: confirm
+ *  with `confirm_resend: true`). */
+export function controlRun(runId, body) {
+  const which = segment(runId);
+  return which ? call(`automation-runs/${which}/control`, { method: "POST", body }) : noId("run");
+}
+
+/** DELETE _claw/automations/<id> → { ok, id, name, was_status, followers: [{ id, key, name }], undo: true }:
+ *  the automation is deleted (switched off first; its runs stay in history). `followers` are the
+ *  automations that started when it finished and now never will. A refusal carries its `code` and
+ *  plain words in `error`: `not_allowed` (owner or admin only), `running` (a run is going),
+ *  `legacy` (an app's own job), `package` (shipped with the app), `not_found`. Resolved, never thrown. */
+export function deleteAutomation(id) {
+  const which = segment(id);
+  return which ? call(`automations/${which}`, { method: "DELETE" }) : noId("automation");
+}
+
+/** POST _claw/automations/<id>/restore → { ok, id, name, status }: the Undo of a delete. A refusal's
+ *  `code` is `key_taken` (another automation took its name since) · `not_allowed` · `not_found`. */
+export function restoreAutomation(id) {
+  const which = segment(id);
+  return which ? call(`automations/${which}/restore`, { method: "POST", body: {} }) : noId("automation");
+}
+
+/** POST _claw/automations/<id>/fixes/<fix> { decision: "keep" | "drop" } → the answer:
+ *  the change the agent drafted from a fix, kept (a NEW version that runs) or dropped.
+ *  A refusal's `code` is `stale` (the live version moved) · `not_allowed` · `moved`
+ *  (decided already) · `not_found`. */
+export function decideFix(id, fixId, decision) {
+  const which = segment(id);
+  const fix = segment(fixId);
+  if (!which) return noId("automation");
+  return fix ? call(`automations/${which}/fixes/${fix}`, { method: "POST", body: { decision } }) : noId("fix");
+}
+
+/** The starting points the platform keeps are the desk's (`GET /api/automation-starts`); claw's
+ *  app door (`_claw/…`) does not serve them, so asking it was a request that always failed and,
+ *  as an unavailable read, was asked again every BACKOFF_MS (found by the store's app test
+ *  suite, 2026-10-13). An app brings its own starting points (its `*-starts.js`), so this
+ *  answers none without a request: { ok: true, data: { source: "code", starts: [] } }. When
+ *  claw serves the route for apps, this is the one line that asks it again. */
+export function automationStarts() {
+  return Promise.resolve({ ok: true, status: 200, data: { source: "code", starts: [] } });
+}
+
+/** POST _claw/automation-draft { ask, app? } → { ok, id, key, name, version, steps }: "Describe it",
+ *  one model call as the member. A refusal is `{ ok: false, code, error, questions? }`;
+ *  `needs_answer` carries the `questions` to ask back. */
+export function draftAutomation(body) {
+  return call("automation-draft", { method: "POST", body });
+}
+
+export const automationsApi = { automations, automation, createAutomation, saveAutomation, runAutomation, automationRuns, automationRun, controlRun, decideFix, automationStarts, draftAutomation, deleteAutomation, restoreAutomation };
+
+/* ---- following a door ----------------------------------------------------- */
+
+/** Is the page shown: the browser tab visible AND the App tab on screen?
+ *  (lib/hooks.js watchShown, the same rule.) */
+function watchShown(onShown) {
+  let onScreen = true;
+  const shown = () => document.visibilityState === "visible" && onScreen;
+  const onVisible = () => {
+    if (shown()) onShown();
+  };
+  let observer = null;
+  if (typeof IntersectionObserver === "function") {
+    observer = new IntersectionObserver((entries) => {
+      const was = onScreen;
+      onScreen = entries[entries.length - 1].isIntersecting;
+      if (onScreen && !was && shown()) onShown();
+    });
+    observer.observe(document.documentElement);
+  }
+  document.addEventListener("visibilitychange", onVisible);
+  return {
+    shown,
+    stop() {
+      observer?.disconnect();
+      document.removeEventListener("visibilitychange", onVisible);
+    },
+  };
+}
+
+const READING = { key: null, data: null, loading: true, error: null, code: null, unavailable: false };
+const NOTHING = { ...READING, loading: false };
+
+/** One door, followed: read when `key` changes and on reload(), then again
+ *  after `next(data)` ms while the page is shown (0 or nothing: no timer).
+ *  A missing door is looked at once a minute and leaves `error` null; a
+ *  refusal keeps the last answer and sets `error` and `code`. */
+function useFollow(read, key, { enabled = true, next } = {}) {
+  const [state, setState] = useState(READING);
+  const [tick, setTick] = useState(0);
+  const readRef = useRef(read);
+  readRef.current = read;
+  const nextRef = useRef(next);
+  nextRef.current = next;
+  const reload = useCallback(() => setTick((t) => t + 1), []);
+
+  useEffect(() => {
+    if (!enabled) return undefined;
+    const controller = new AbortController();
+    let alive = true;
+    let timer = null;
+    let inflight = false;
+    let again = false;
+    let unavailable = false;
+    let last = null;
+
+    const schedule = () => {
+      clearTimeout(timer);
+      timer = null;
+      if (!alive || !screen.shown()) return;
+      if (again) {
+        again = false;
+        load();
+        return;
+      }
+      const ms = unavailable ? BACKOFF_MS : Number(nextRef.current?.(last)) || 0;
+      if (ms > 0) timer = setTimeout(load, ms);
+    };
+    const load = async () => {
+      clearTimeout(timer);
+      timer = null;
+      if (!alive || !screen.shown()) return;
+      if (inflight) {
+        again = true;
+        return;
+      }
+      inflight = true;
+      const r = await readRef.current(controller.signal);
+      inflight = false;
+      if (!alive || r?.aborted) return;
+      unavailable = Boolean(r?.unavailable);
+      if (r?.ok && r.data && typeof r.data === "object" && !Array.isArray(r.data)) {
+        last = r.data;
+        setState({ key, data: r.data, loading: false, error: null, code: null, unavailable: false });
+      } else {
+        const why = r?.ok
+          ? { error: "the platform answered something unexpected", code: null, unavailable: false }
+          : unavailable
+            ? { error: null, code: null, unavailable: true }
+            : { error: r?.error || "the platform did not answer", code: r?.code ?? null, unavailable: false };
+        setState((s) => ({ key, data: s.key === key ? s.data : null, loading: false, ...why }));
+      }
+      schedule();
+    };
+
+    const screen = watchShown(load);
+    load();
+    return () => {
+      alive = false;
+      controller.abort();
+      clearTimeout(timer);
+      screen.stop();
+    };
+  }, [key, enabled, tick]);
+
+  // A state kept for another read is not shown.
+  const current = enabled ? (state.key === key ? state : READING) : NOTHING;
+  return { data: current.data, loading: current.loading, error: current.error, code: current.code, unavailable: current.unavailable, reload };
+}
+
+/** A press that is out: set while it runs, cleared after, only if still mounted. */
+function useBusy() {
+  const [busy, setBusy] = useState(null);
+  const alive = useRef(true);
+  useEffect(() => {
+    alive.current = true;
+    return () => {
+      alive.current = false;
+    };
+  }, []);
+  const press = useCallback(async (what, work) => {
+    if (alive.current) setBusy(what);
+    try {
+      return await work();
+    } finally {
+      if (alive.current) setBusy(null);
+    }
+  }, []);
+  return [busy, press, alive];
+}
+
+/* ---- the hooks ------------------------------------------------------------- */
+
+/**
+ * This app's automations, for the `automation-list` block (GET _claw/automations):
+ *
+ *   const { automations, busy, setStatus, create } = useAutomations();
+ *
+ *   automations  the rows, as the door sends them (see automations())
+ *   busy         { [id]: "switch" } while a press is out
+ *   setStatus(id, on)   the switch: resolves the answer, then looks again.
+ *                       Refusals: `no_live` (keep a version first), `not_found`
+ *   create(definition, { note?, goLive? })   a new automation; resolves
+ *                       { ok, data: { id } } or { ok: false, error, problems }
+ *   starts       the starting points the platform keeps (the desk's GET automation-starts), raw:
+ *                [{ id, name, blurb, needs, ai, credits, per?, glyph, definition }]. Give the list
+ *                `startsFromPlatform(starts)` (automation-model). [] when the platform has none
+ *                or this surface may not read them; never an error.
+ *   describe(ask, app?)   "Describe it": the platform drafts an automation from a sentence (one
+ *                model call, as the member). Resolves { ok: true, id, key, name, version, steps },
+ *                or { ok: false, error, code, questions? } (`needs_answer` carries `questions`),
+ *                or { ok: false, code: "unavailable" } on a claw without it; never thrown.
+ *   describing   true while it drafts
+ *   triggers     what can start an automation here, for the `trigger-picker` block:
+ *                { choices: [{ type, label, hint, available, why? }],
+ *                  apps: [{ name, actions: [{ name, description }], kinds, topics }],
+ *                  automations: [{ key, name }] }, or null from a platform without them
+ *   loading, error, code, unavailable, reload
+ *
+ * Looks every 30 s, every 5 s while one is running, and not at all while
+ * the page is hidden. On a claw from before the engine it is `unavailable`.
+ */
+export function useAutomations({ every = IDLE_MS } = {}) {
+  const watched = useFollow((signal) => automations({ signal }), "automations", {
+    next: (data) => (listOf(data?.automations).some((a) => (a?.active_runs ?? 0) > 0) ? RUNNING_MS : every),
+  });
+  const { reload } = watched;
+  const [busyId, press] = useBusy();
+  const [switching, setSwitching] = useState({});
+  // The starting points are read once (they do not move while the page is open), and a
+  // surface that may not read them, or a claw without them, simply has none.
+  const startsRead = useFollow((signal) => automationStarts({ signal }), "automation-starts", { next: () => 0 });
+  const starts = useMemo(() => listOf(startsRead.data?.starts), [startsRead.data]);
+
+  const setStatus = useCallback(
+    async (id, on) => {
+      setSwitching((s) => ({ ...s, [id]: "switch" }));
+      const r = await saveAutomation(id, { status: on ? "on" : "off" });
+      setSwitching((s) => {
+        const next = { ...s };
+        delete next[id];
+        return next;
+      });
+      reload();
+      return r;
+    },
+    [reload],
+  );
+
+  const create = useCallback(
+    (definition, { note, goLive } = {}) =>
+      press("create", async () => {
+        const r = await createAutomation({ definition, ...(note ? { note } : {}), ...(goLive ? { go_live: true } : {}) });
+        if (r.ok) reload();
+        return r;
+      }),
+    [press, reload],
+  );
+
+  const describe = useCallback(
+    (ask, app) =>
+      press("describe", async () => {
+        const text = typeof ask === "string" ? ask.trim() : "";
+        if (!text) return { ok: false, error: "Say what it should do first.", code: "empty" };
+        const r = await draftAutomation({ ask: text, ...(typeof app === "string" && app ? { app } : {}) });
+        if (r.unavailable) return { ok: false, code: "unavailable", error: "Describing an automation is not set up here yet.", unavailable: true };
+        if (!r.ok) return { ok: false, error: r.error, code: r.code ?? "refused", ...(r.questions ? { questions: r.questions } : {}) };
+        const body = r.data && typeof r.data === "object" ? r.data : {};
+        // A refusal can arrive with a 200: the body says.
+        if (body.ok === false) {
+          const questions = Array.isArray(body.questions) ? body.questions.filter((q) => typeof q === "string" && q.trim()) : undefined;
+          return { ok: false, error: body.error || "That did not work.", code: typeof body.code === "string" ? body.code : "refused", ...(questions ? { questions } : {}) };
+        }
+        reload();
+        return { ...body, ok: true };
+      }),
+    [press, reload],
+  );
+
+  const rows = useMemo(() => listOf(watched.data?.automations), [watched.data]);
+  return { automations: rows, triggers: watched.data?.triggers ?? null, starts, describe, describing: busyId === "describe", busy: switching, creating: busyId === "create", setStatus, create, loading: watched.loading, error: watched.error, code: watched.code, unavailable: watched.unavailable, reload };
+}
+
+/**
+ * One automation, for the `automation-builder` and `run-view` blocks
+ * (GET _claw/automations/<id> and its runs):
+ *
+ *   const a = useAutomation(id);
+ *   a.automation   the row: { id, key, name, status, live_version, draft_version, tz, owner_kind … }
+ *   a.live, a.draft  { version, definition, … } or null
+ *   a.definition   the draft if there is one, else the live one: what the builder opens
+ *   a.versions     [{ version, kind, author, note, created_at }]
+ *   a.estimate, a.estimateDraft   what a run is expected to cost: { credits, credits_max, cap, steps }
+ *   a.runs         [{ id, status, trigger_type, is_test, created_at, credits … }], newest first
+ *   a.suggestions  the changes the agent drafted from failed runs, still waiting for a person:
+ *                  [{ id, run_id, why, base_version, stale, patch, created_at }]
+ *   a.keepSuggestion(id)  keep one: a NEW version that runs (author: agent, kept by you);
+ *                  refused with `stale` when the automation moved on since
+ *   a.dropSuggestion(id)  forget one
+ *   a.hook         a webhook trigger's address: { path, has_secret, rotated_at, last_received_at },
+ *                  or null; never the secret
+ *   a.rotateHook() make the webhook's secret (or replace it; the old one stops at once);
+ *                  resolves { ok: true, hook: { path, secret } }: the secret is shown once
+ *   a.tests        { live: TestView | null, draft: TestView | null }, TestView = { version, passed, exempt,
+ *                  last: { run_id, status, ended_at, credits, would } | null }: whether a test of that
+ *                  version passed (the editor's `tests` prop). Keep and Live need a passed test unless
+ *                  the member skips it. null from a platform without it.
+ *   a.busy         "save" | "keep" | "live" | "test" | "fix" | "hook" while a press is out
+ *   a.save(definition, how?)   a draft version; resolves the answer ({ ok: false, problems } on a refusal).
+ *                        `how` is a note (a string) or `{ baseVersion, note? }`: the editor passes
+ *                        `{ baseVersion }`, the version its working copy began on, and the save names THAT
+ *                        version (`expect_version`), so a newer draft (the agent's) is refused with
+ *                        `changed` and `latest` instead of being buried. With no base it names the newest
+ *                        version this hook has read.
+ *   a.keep({ skipTest }?)   the draft becomes the version that runs. Refused with `needs_test` until a
+ *                        test of it passed; `skipTest: true` is the member's own, deliberate second
+ *                        press (sends `skip_test`); an agent never passes it
+ *   a.setLive(on, { skipTest }?)   the Live switch; same refusal, same override
+ *   a.test({ inputs, sample, dry }?)   one TEST of the draft (or live) version: it reads real data and
+ *                        changes nothing (`dry` is true unless you pass `dry: false` for a real run);
+ *                        `sample` is a pretend trigger payload; resolves { data: { run_id, test, dry,
+ *                        version } }. A plain object with none of those keys is taken as the inputs
+ *                        themselves (as before).
+ *   loading, error, code, unavailable, reload
+ *
+ * Nothing is read while `id` is empty. Each press looks again after.
+ */
+export function useAutomation(id, { every = IDLE_MS } = {}) {
+  const enabled = Boolean(segment(id));
+  const detail = useFollow((signal) => automation(id, { signal }), JSON.stringify(["automation", id ?? null]), { enabled, next: () => every });
+  const runsRead = useFollow((signal) => automationRuns(id, { limit: 30, signal }), JSON.stringify(["automation-runs", id ?? null]), {
+    enabled,
+    next: (data) => (listOf(data?.runs).some((r) => ACTIVE.has(r?.status)) ? RUNNING_MS : every),
+  });
+  const [busy, press] = useBusy();
+  const reloadAll = useCallback(() => {
+    detail.reload();
+    runsRead.reload();
+  }, [detail.reload, runsRead.reload]);
+
+  const d = detail.data;
+  const versions = useMemo(() => listOf(d?.versions), [d]);
+  const latest = versions.reduce((m, v) => Math.max(m, Number(v?.version) || 0), 0);
+  const live = d?.live ?? null;
+  const draft = d?.draft ?? null;
+  const suggestions = useMemo(() => listOf(d?.suggestions), [d]);
+
+  const change = useCallback(
+    (what, body) =>
+      press(what, async () => {
+        const r = await saveAutomation(id, body);
+        reloadAll();
+        return r;
+      }),
+    [id, press, reloadAll],
+  );
+  const save = useCallback(
+    (definition, how) => {
+      const own = how && typeof how === "object";
+      const note = own ? how.note : how;
+      const base = own && Number.isInteger(how.baseVersion) ? how.baseVersion : latest;
+      return change("save", { definition, expect_version: base, ...(typeof note === "string" && note ? { note } : {}) });
+    },
+    [change, latest],
+  );
+  const keep = useCallback((o) => change("keep", { keep: true, ...(o && o.skipTest === true ? { skip_test: true } : {}) }), [change]);
+  const setLive = useCallback((on, o) => change("live", { status: on ? "on" : "off", ...(o && o.skipTest === true ? { skip_test: true } : {}) }), [change]);
+  const decide = useCallback(
+    (fixId, decision) =>
+      press("fix", async () => {
+        const r = await decideFix(id, fixId, decision);
+        reloadAll();
+        return r;
+      }),
+    [id, press, reloadAll],
+  );
+  const rotateHook = useCallback(async () => {
+    const r = await change("hook", { hook: "rotate" });
+    return r.ok ? { ok: true, hook: r.data?.hook ?? null } : r;
+  }, [change]);
+  const keepSuggestion = useCallback((fixId) => decide(fixId, "keep"), [decide]);
+  const dropSuggestion = useCallback((fixId) => decide(fixId, "drop"), [decide]);
+  const test = useCallback(
+    (given = {}) =>
+      press("test", async () => {
+        const version = draft?.version ?? live?.version;
+        const options = given && typeof given === "object" && ("inputs" in given || "sample" in given || "dry" in given) ? given : { inputs: given };
+        const inputs = options.inputs && typeof options.inputs === "object" ? options.inputs : {};
+        const r = await runAutomation(id, {
+          inputs,
+          ...(options.sample !== undefined ? { sample: options.sample } : {}),
+          dry: options.dry !== false,
+          ...(version !== undefined ? { version } : {}),
+        });
+        reloadAll();
+        return r;
+      }),
+    [id, press, reloadAll, draft, live],
+  );
+
+  return {
+    automation: d?.automation ?? null,
+    live,
+    draft,
+    definition: draft?.definition ?? live?.definition ?? null,
+    versions,
+    estimate: d?.estimate_draft ?? d?.estimate ?? null,
+    estimateDraft: d?.estimate_draft ?? null,
+    tests: d?.tests && typeof d.tests === "object" ? { live: d.tests.live ?? null, draft: d.tests.draft ?? null } : null,
+    runs: listOf(runsRead.data?.runs),
+    suggestions,
+    keepSuggestion,
+    dropSuggestion,
+    hook: d?.hook ?? null,
+    rotateHook,
+    busy,
+    save,
+    keep,
+    setLive,
+    test,
+    loading: detail.loading,
+    error: detail.error,
+    code: detail.code,
+    unavailable: detail.unavailable,
+    reload: reloadAll,
+  };
+}
+
+/**
+ * One run's account, for the `run-view` block (GET _claw/automation-runs/<id>):
+ *
+ *   const { run, steps, stepsVisible, automation, definition } = useAutomationRun(runId);
+ *
+ *   run           { id, status, version, trigger_type, is_test, dry, credits, cap_credits, result, error,
+ *                 paused, cap_bonus … }. `dry` is a TEST run (it read real data and changed nothing);
+ *                 its `result.dry` says what each step would have done.
+ *   steps         [{ path, step_id, kind, attempt, status, credits, error, input?, output?, fix? }]
+ *   stepsVisible  the member may read what went in and out of each step
+ *   definition    the definition the run was pinned to, when the platform sends it, else null
+ *   fixes         the fixer's attempts on this run, with the changes it drafted
+ *   detail        the answer as sent, for RunView's `detail` prop
+ *   control(op, { path?, input?, confirmNotSent?, raiseBy?, confirmResend? })
+ *                 pause · resume · stop · retry · skip · edit · retry_from: RunView's `onControl`. Resolves
+ *                 the answer ({ ok: false, error, code } on a refusal, never thrown); the run
+ *                 is read again after.
+ *   keepFix(stepId), dropFix(stepId)   keep or drop the change the agent drafted for a step it
+ *                 fixed (RunView's `onKeepFix` / `onDropFix`); refused with `stale` when the
+ *                 automation moved on
+ *   busy          the op out ("pause", "retry", …, or "fix")
+ *
+ * Nothing is read while `runId` is empty. Looks every 2.5 s while the run
+ * goes; a run that has ended is read once.
+ */
+export function useAutomationRun(runId) {
+  const enabled = Boolean(segment(runId));
+  const watched = useFollow((signal) => automationRun(runId, { signal }), JSON.stringify(["automation-run", runId ?? null]), {
+    enabled,
+    next: (data) => (ACTIVE.has(data?.run?.status) ? RUN_FOLLOW_MS : 0),
+  });
+  const d = watched.data;
+  const fixes = useMemo(() => listOf(d?.fixes), [d]);
+  const [busy, press] = useBusy();
+  const { reload } = watched;
+  const control = useCallback(
+    (op, o = {}) =>
+      press(op, async () => {
+        const body = {
+          op,
+          ...(o.path ? { path: o.path } : {}),
+          ...(o.input !== undefined ? { input: o.input } : {}),
+          ...(o.confirmNotSent ? { confirm_not_sent: true } : {}),
+          ...(Number(o.raiseBy) > 0 ? { raise_cap_by: Number(o.raiseBy) } : {}),
+          ...(o.confirmResend ? { confirm_resend: true } : {}),
+        };
+        const r = await controlRun(runId, body);
+        reload();
+        return r;
+      }),
+    [runId, press, reload],
+  );
+  const automationId = d?.run?.automation_id ?? d?.automation?.id ?? null;
+  const decide = useCallback(
+    (stepId, decision) => {
+      // The newest change the fixer drafted for the step that a person has not decided.
+      let draft = null;
+      for (const f of fixes) if (f.step_id === stepId) for (const x of f.drafts ?? []) if (x.status === "proposed") draft = x;
+      if (!draft || !automationId) return Promise.resolve({ ok: false, status: 0, error: "The agent drafted nothing to keep for that step.", unavailable: false });
+      return press("fix", async () => {
+        const r = await decideFix(automationId, draft.id, decision);
+        reload();
+        return r;
+      });
+    },
+    [fixes, automationId, press, reload],
+  );
+  const keepFix = useCallback((stepId) => decide(stepId, "keep"), [decide]);
+  const dropFix = useCallback((stepId) => decide(stepId, "drop"), [decide]);
+  return {
+    run: d?.run ?? null,
+    steps: listOf(d?.steps),
+    stepsVisible: Boolean(d?.steps_visible),
+    automation: d?.automation ?? null,
+    definition: d?.definition ?? null,
+    fixes,
+    detail: d && d.run ? { run: d.run, automation: d.automation ?? null, steps: listOf(d.steps), steps_visible: Boolean(d.steps_visible), fixes } : null,
+    control,
+    keepFix,
+    dropFix,
+    busy,
+    loading: watched.loading,
+    error: watched.error,
+    code: watched.code,
+    unavailable: watched.unavailable,
+    reload: watched.reload,
+  };
+}