makersclaw 0.3.2 → 0.4.0

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

@@ -1,8 +1,8 @@
 "use client";
 
-import { useCallback, useEffect, useRef, useState } from "react";
-import { claw, publishStatus } from "./claw";
-import { cancelJob, startJob } from "./platform";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { claw, publishDesk, publishStatus } from "./claw";
+import { ask, cancelJob, openRequest, requests as readRequests, startJob, stopRequest } from "./platform";
 
 // The React side of the _claw API, without any look: fetching, polling,
 // streaming and cleanup. A surface renders what comes back and owns every
@@ -11,9 +11,13 @@ import { cancelJob, startJob } from "./platform";
 // There is no chat, runs or activity hook here, and there will not be:
 // those are STANDING surfaces and the OS draws them as tabs on the app
 // window (docs/ARTIFACT-CONTRACTS.md §9). `useJob` is the other thing —
-// work a founder commissions from inside the app, which is not a surface
-// at all: it opens because they pressed something and it closes when the
-// work lands (SOP §2.3, ARTIFACT-CONTRACTS §9f).
+// work a founder asks for from inside the app, which is not a surface at
+// all: it opens because they pressed something and it closes when the
+// work lands (SOP §2.3, ARTIFACT-CONTRACTS §9f). Since 0.4.0 that work is
+// a request: the conversation lives in the desk's agent column, and the
+// app follows only its status. `useRequests` is the same requests seen
+// from a surface: the asks in flight on this app, so an empty table can
+// show the work coming instead of a blank.
 //
 // While the gateway has no _claw routes yet (`unavailable`), polls back
 // off to once a minute so a preview that is still being wired does not
@@ -21,6 +25,64 @@ import { cancelJob, startJob } from "./platform";
 
 const BACKOFF_MS = 60000;
 
+/** How often useRequests looks again while nothing is working. */
+const IDLE_MS = 20000;
+
+/** How often useJob looks at its request while the work goes on. */
+const FOLLOW_MS = 2500;
+
+// A request's status is one of eleven (claw's shared/src/requests.ts).
+// Seven are live: the work is still going. `answered` is open but not
+// live — the agent answered and waits. Three are closed.
+const LIVE = new Set(["routing", "queued", "installing", "setting_up", "building", "working", "needs_you"]);
+const CLOSED = new Set(["done", "stopped", "didnt_finish"]);
+
+/**
+ * Is the page shown: the browser tab visible AND the App tab on screen?
+ * In the desk the App tab stays mounted, hidden, behind the window's
+ * other tabs, and visibilityState still reads "visible" there; only an
+ * IntersectionObserver on the root sees it (app/frame.js says why, and
+ * app/auto-refresh.jsx watches it the same way). `onShown` runs each
+ * time the page comes back.  → { shown(), stop() }
+ */
+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);
+    },
+  };
+}
+
+// An ask made through useJob tells every useRequests on the page, so the
+// empty state shows the new work at once instead of at its next look.
+const asked = new Set();
+
+function onAsked(listener) {
+  asked.add(listener);
+  return () => asked.delete(listener);
+}
+
+function announceAsk() {
+  for (const listener of [...asked]) listener();
+}
+
 /**
  * GET one _claw route. Fetches on mount, again every `every` ms while the
  * tab is visible, and on reload(). A failed poll keeps the last data and
@@ -65,8 +127,9 @@ export function useClaw(path, { every, enabled = true } = {}) {
 }
 
 /**
- * Who this app is (_claw/me). Also publishes the status onto <html>
- * so reportError can tell a preview fault from a runtime one.
+ * Who this app is (_claw/me). Also publishes the status and the desk's
+ * origin onto <html>: reportError reads the status to tell a preview
+ * fault from a runtime one, and openInDesk posts to the origin.
  *   → { artifact, user, blueprint, loading, error, unavailable, reload }
  */
 export function useArtifact() {
@@ -75,9 +138,135 @@ export function useArtifact() {
   useEffect(() => {
     publishStatus(artifact?.status);
   }, [artifact?.status]);
+  useEffect(() => {
+    if (data) publishDesk(data.desk_origin);
+  }, [data]);
   return { artifact, user: data?.user ?? null, blueprint: data?.blueprint ?? null, ...rest };
 }
 
+/** Does a request belong to what a surface asked for? Each filter given
+ *  is a way in: a screen's ask made on this surface, or work on this job
+ *  wherever it was asked for (a desk ask handed to the app has no
+ *  surface, only its job). No filter: every request. */
+function belongs(request, { surface, job }) {
+  if (!surface && !job) return true;
+  return Boolean((surface && request.surface === surface) || (job && request.job_key === job));
+}
+
+function ended(request) {
+  return CLOSED.has(request.status) || Boolean(request.ended_at);
+}
+
+/**
+ * This app's requests: the work asked of its agent, from a screen or
+ * from the desk, by anyone in the workspace. For an empty state that
+ * shows the live work instead of a blank (the LiveEmpty part):
+ *
+ *   const work = useRequests({ surface: "deals" });
+ *   if (!rows.length) return <LiveEmpty work={work} surface="deals" … />;
+ *
+ *   requests     every request the gateway returned: the live ones and
+ *                those that ended in the last day
+ *   live         the ones not ended, for this surface or job (a filter
+ *                given is a way in: the surface's own asks, or the job's
+ *                work from anywhere)
+ *   run          the app's scheduled run while one is going, or null
+ *   loading, error, unavailable, reload
+ *   open(r)      open a request's conversation in the desk's column
+ *   stop(id)     stop one, then look again
+ *
+ * Looks every `every` ms while work is going, every 20 s when nothing
+ * is, once a minute while the gateway has no such route — and only while
+ * the page is shown: not behind the window's other tabs, not in a hidden
+ * browser tab. Coming back looks at once.
+ */
+export function useRequests({ surface, job, every = 5000 } = {}) {
+  const [state, setState] = useState({ requests: [], run: null, loading: true, error: null, unavailable: false });
+  const [tick, setTick] = useState(0);
+  const reload = useCallback(() => setTick((t) => t + 1), []);
+  const filterRef = useRef({ surface, job });
+  filterRef.current = { surface, job };
+  const often = Math.max(Number(every) || 5000, 1000);
+
+  useEffect(() => {
+    const controller = new AbortController();
+    let alive = true;
+    let timer = null;
+    let inflight = false;
+    let again = false;
+    let unavailable = false;
+    let working = false;
+
+    const schedule = () => {
+      clearTimeout(timer);
+      timer = null;
+      // Hidden: no timer at all. Coming back on screen looks again.
+      if (!alive || !screen.shown()) return;
+      // Asked to look while a look was out: that answer may predate the
+      // ask, so look once more now rather than at the next tick.
+      if (again) {
+        again = false;
+        load();
+        return;
+      }
+      timer = setTimeout(load, unavailable ? BACKOFF_MS : working ? often : IDLE_MS);
+    };
+    const load = async () => {
+      clearTimeout(timer);
+      timer = null;
+      if (!alive || !screen.shown()) return;
+      if (inflight) {
+        again = true;
+        return;
+      }
+      inflight = true;
+      const r = await readRequests({ signal: controller.signal });
+      inflight = false;
+      if (!alive || r.aborted) return;
+      unavailable = Boolean(r.unavailable);
+      if (r.ok) {
+        const list = Array.isArray(r.data?.requests) ? r.data.requests : [];
+        const run = r.data?.run ?? null;
+        if (r.data?.desk_origin) publishDesk(r.data.desk_origin);
+        working = Boolean(run) || list.some((q) => LIVE.has(q.status) && belongs(q, filterRef.current));
+        setState({ requests: list, run, loading: false, error: null, unavailable: false });
+      } else {
+        working = false;
+        setState((s) => ({ ...s, loading: false, error: r.error, unavailable }));
+      }
+      schedule();
+    };
+
+    const screen = watchShown(load);
+    const unsubscribe = onAsked(load);
+    load();
+    return () => {
+      alive = false;
+      controller.abort();
+      clearTimeout(timer);
+      screen.stop();
+      unsubscribe();
+    };
+  }, [often, tick]);
+
+  const live = useMemo(
+    () => state.requests.filter((q) => q && !ended(q) && belongs(q, { surface, job })),
+    [state.requests, surface, job],
+  );
+
+  const open = useCallback((request) => openRequest(request), []);
+  const stop = useCallback(
+    async (id) => {
+      const r = await stopRequest(id);
+      reload();
+      return r;
+    },
+    [reload],
+  );
+
+  return { ...state, live, reload, open, stop };
+}
+
 /** A settled tool call closes the LAST running step with that name, not
  *  the first: two calls to the same tool in one turn settle in order. */
 function settleStep(steps, name, status) {
@@ -99,33 +288,118 @@ const IDLE = {
   sessionId: null,
   progress: 0,
   finishedAt: null,
+  // From the request the job is (null on a claw before _claw/ask).
+  status: null,
+  requestId: null,
+  queued: false,
+  queuedAfter: null,
+  needsYou: false,
+  liveLine: null,
+  count: null,
+  target: null,
+  request: null,
 };
 
+/** A request's status as a step's: running | done | failed, the words
+ *  the job panel reads. */
+function stepStatus(status) {
+  if (LIVE.has(status)) return "running";
+  return status === "done" || status === "answered" ? "done" : "failed";
+}
+
 /**
- * Commission work and follow it: the job half of SOP §2.3. One job at a
- * time per hook — call it once per place the founder can start something.
+ * What useJob shows for a request (_claw/ask's and _claw/requests'
+ * AppRequestView). Pure, so the template's tests hold it to each status.
+ * The one step is the request itself, labelled with its line; the text
+ * is empty because the agent's account is in the desk's column now.
+ */
+export function jobFromRequest(request) {
+  const r = request && typeof request === "object" ? request : {};
+  const status = typeof r.status === "string" ? r.status : null;
+  const line = r.line || null;
+  return {
+    running: LIVE.has(status),
+    status,
+    requestId: r.id ?? null,
+    sessionId: r.app_session_id ?? null,
+    queued: status === "queued",
+    queuedAfter: r.queued ?? null,
+    needsYou: status === "needs_you",
+    liveLine: line,
+    count: r.progress?.n ?? null,
+    target: r.progress?.of ?? null,
+    steps: status ? [{ name: "request", label: line || r.title || "", status: stepStatus(status) }] : [],
+    text: "",
+    error: status === "didnt_finish" ? line || "Didn't finish" : status === "stopped" ? "Stopped" : null,
+    finishedAt:
+      status === "done" || status === "answered" ? r.ended_at || r.updated_at || new Date().toISOString() : null,
+    request: request ?? null,
+  };
+}
+
+// A thread this screen may not continue gets a thread of its own, once:
+// a teammate's (403), or one the claw holds no request for (404) — a
+// session kept on a row from the 0.3.x door, before asks were requests.
+const START_FRESH = new Set(["not_your_thread", "unknown_thread"]);
+
+/** On the 0.3.x door there is no context field: what the ask carries
+ *  rides in the message instead, as the platform's hand-off writes it. A
+ *  0.3.x call site passes neither, so its message goes as it always did. */
+function legacyMessage(text, row, how) {
+  const parts = [text];
+  if (how) parts.push(String(how));
+  if (row && typeof row === "object") parts.push(`The row: ${JSON.stringify(row).slice(0, 8000)}`);
+  return parts.join("\n\n");
+}
+
+/**
+ * Ask the app's agent for work and follow it: the job half of SOP §2.3.
+ * One job at a time per hook — call it once per place the founder can
+ * start something.
  *
  *   const job = useJob();
  *   <button onClick={() => job.start("Draft a launch checklist for …")}>
  *
+ * start() asks (lib/platform.js, ask): the platform makes the ask a
+ * request, hands it to the app's agent, and the desk opens its
+ * conversation in the agent column. The hook then follows the request's
+ * status until it ends. start resolves once the ask is taken or refused;
+ * on a claw from before _claw/ask it streams the 0.3.x way and resolves
+ * when the job ends, as it always did.
+ *
  * State, for the panel the surface draws:
  *   running     a job is in flight
+ *   status      the request's status (working, queued, needs_you, done, …)
+ *   queued      waiting its turn; queuedAfter = { reason, after_id,
+ *               after_title }
+ *   needsYou    the agent waits on the founder: open() takes them to the
+ *               question in the column
+ *   liveLine    the one line the desk shows for it ("Drafting · 12 of 50")
+ *   count, target   the counted progress (12, 50), or null
  *   steps       [{ name, label, status }] — `label` is the founder's
- *               phrase ("Searching the web"), `status` running | done |
- *               failed. Show labels; the raw name is there for debugging.
- *   text        what the agent has written so far, growing. This is its
- *               account of the work, NOT the deliverable — the deliverable
- *               is rows on a surface.
- *   progress    bumps every time a step settles. Feed it to a data hook's
+ *               phrase, `status` running | done | failed. Show labels;
+ *               the raw name is there for debugging.
+ *   text        on the 0.3.x path, what the agent has written so far —
+ *               its account, NOT the deliverable. Empty on the request
+ *               path: the account is in the column.
+ *   progress    bumps every time the work moves. Feed it to a data hook's
  *               reload so rows appear as they land:
  *                 useEffect(() => { reload(); }, [job.progress]);
  *   error       a message, or null
  *   sessionId   the thread. Pass it back to start() to refine what this
  *               job produced; keep it on the object's row and the founder
  *               can pick the conversation up where the thing lives.
+ *   requestId   the request, or null on the 0.3.x path
  *   finishedAt  ISO time the last job settled, or null
  *
- * Actions: start(message, { sessionId }) · cancel() · reset().
+ * Actions: start(message, { sessionId, row, how, job, list, open }) ·
+ * cancel() · reset() · open().
+ *
+ *   row     the row the ask is about, as context for the agent
+ *   how     instructions for the agent only (the AGENTS.md section)
+ *   job     a declared job's key; by default the platform picks the job
+ *           whose view is this surface, else the app's only job
+ *   open    false keeps the desk's column where it is
  *
  * The panel this drives must not exist when nothing is running — that is
  * §2.3's test, and a standing one is the monitoring console §2.7 warns
@@ -135,6 +409,10 @@ export function useJob() {
   const [state, setState] = useState(IDLE);
   const abortRef = useRef(null);
   const sessionRef = useRef(null);
+  const requestRef = useRef(null); // the request followed
+  const pathRef = useRef(null); // "request" | "legacy": which door the job went through
+  const followRef = useRef(null); // stops following
+  const movedRef = useRef(null); // the last status|progress|updated_at seen
   const aliveRef = useRef(true);
 
   useEffect(() => {
@@ -142,16 +420,81 @@ export function useJob() {
     return () => {
       aliveRef.current = false;
       abortRef.current?.abort();
+      followRef.current?.();
+      followRef.current = null;
     };
   }, []);
 
-  const start = useCallback(async (message, { sessionId } = {}) => {
-    const text = String(message ?? "").trim();
-    if (!text) return { ok: false, error: "nothing to ask" };
-    abortRef.current?.abort();
-    const controller = new AbortController();
-    abortRef.current = controller;
+  const apply = useCallback((request) => {
+    if (!aliveRef.current) return;
+    requestRef.current = request;
+    const next = jobFromRequest(request);
+    if (next.sessionId) sessionRef.current = next.sessionId;
+    const mark = [request.status, request.progress?.n, request.progress?.of, request.updated_at].join("|");
+    const moved = mark !== movedRef.current;
+    movedRef.current = mark;
+    setState((s) => ({
+      ...s,
+      ...next,
+      sessionId: next.sessionId ?? s.sessionId,
+      progress: moved ? s.progress + 1 : s.progress,
+      finishedAt: next.finishedAt ? (s.finishedAt ?? next.finishedAt) : null,
+    }));
+  }, []);
+
+  // Look at the request every 2.5 s while it is live and the page is
+  // shown; stop when it ends. Hidden, nothing is asked; coming back looks
+  // at once.
+  const follow = useCallback(
+    (id, signal) => {
+      let timer = null;
+      let stopped = false;
+      let inflight = false;
+      const stop = () => {
+        stopped = true;
+        clearTimeout(timer);
+        screen.stop();
+      };
+      const schedule = (ms = FOLLOW_MS) => {
+        clearTimeout(timer);
+        timer = null;
+        if (!stopped && screen.shown()) timer = setTimeout(poll, ms);
+      };
+      const poll = async () => {
+        clearTimeout(timer);
+        timer = null;
+        if (stopped || inflight || !screen.shown()) return;
+        inflight = true;
+        const r = await readRequests({ id, signal });
+        inflight = false;
+        if (stopped || !aliveRef.current || r.aborted) return;
+        const request = r.ok ? r.data?.request : null;
+        if (request?.id) {
+          apply(request);
+          if (LIVE.has(request.status)) schedule();
+          else stop();
+          return;
+        }
+        if (r.status === 404) {
+          // Gone, or no longer this app's: stop following, close quietly.
+          stop();
+          setState((s) => ({ ...s, running: false }));
+          return;
+        }
+        schedule(FOLLOW_MS * 4); // a blip: look again, a little later
+      };
+      const screen = watchShown(poll);
+      followRef.current = stop;
+      schedule();
+    },
+    [apply],
+  );
+
+  // The 0.3.x door, as it was: _claw/chat streamed into the app. Taken
+  // only on a claw that has no _claw/ask.
+  const legacyStart = useCallback(async (text, { sessionId, signal }) => {
     const thread = sessionId ?? null;
+    pathRef.current = "legacy";
     sessionRef.current = thread;
     setState({ ...IDLE, running: true, sessionId: thread });
 
@@ -187,12 +530,9 @@ export function useJob() {
       }
     };
 
-    const result = await startJob(text, {
-      sessionId: thread ?? undefined,
-      onEvent,
-      signal: controller.signal,
-    });
-    if (!aliveRef.current) return result;
+    const result = await startJob(text, { sessionId: thread ?? undefined, onEvent, signal });
+    // Aborted means a new start, a cancel or a reset already set the state.
+    if (!aliveRef.current || signal.aborted) return result;
     // A stream that ends without `done` (a dropped connection, a 4xx
     // before the first frame) must still leave the panel closable.
     if (!result.ok && !result.aborted)
@@ -201,18 +541,99 @@ export function useJob() {
     return result;
   }, []);
 
+  const start = useCallback(
+    async (message, { sessionId, row, how, job = true, list, open } = {}) => {
+      const text = String(message ?? "").trim();
+      if (!text) return { ok: false, error: "nothing to ask" };
+      abortRef.current?.abort();
+      followRef.current?.();
+      followRef.current = null;
+      const controller = new AbortController();
+      abortRef.current = controller;
+      const thread = sessionId ?? null;
+      pathRef.current = "request";
+      sessionRef.current = thread;
+      requestRef.current = null;
+      movedRef.current = null;
+      setState({ ...IDLE, running: true, sessionId: thread });
+
+      const asking = (session) =>
+        ask({ text, row, how, job, list, sessionId: session ?? undefined, open, signal: controller.signal });
+      let result = await asking(thread);
+      if (!result.ok && thread && START_FRESH.has(result.code) && !controller.signal.aborted) {
+        sessionRef.current = null;
+        setState((s) => ({ ...s, sessionId: null }));
+        result = await asking(null);
+      }
+      if (!aliveRef.current || controller.signal.aborted) return result;
+
+      // A 404 that names no refusal: a claw from before _claw/ask. Its
+      // _claw/chat still runs the job, so a 0.4.0 app works there too.
+      // The thread is the one still held: after a retry that dropped a
+      // teammate's, it is none — never theirs.
+      if (!result.ok && result.status === 404 && !result.code)
+        return legacyStart(legacyMessage(text, row, how), { sessionId: sessionRef.current, signal: controller.signal });
+
+      if (!result.ok) {
+        setState((s) => ({ ...s, running: false, error: s.error ?? result.error }));
+        return result;
+      }
+      const request = result.data?.request;
+      if (!request?.id) {
+        setState((s) => ({ ...s, running: false, finishedAt: new Date().toISOString() }));
+        return result;
+      }
+      apply(request);
+      announceAsk();
+      if (LIVE.has(request.status)) follow(request.id, controller.signal);
+      return result;
+    },
+    [apply, follow, legacyStart],
+  );
+
   const cancel = useCallback(async () => {
     abortRef.current?.abort();
-    const id = sessionRef.current;
-    setState((s) => ({ ...s, running: false, finishedAt: new Date().toISOString() }));
-    if (id) await cancelJob(id);
+    followRef.current?.();
+    followRef.current = null;
+    const request = requestRef.current;
+    const live = Boolean(request?.id && LIVE.has(request.status));
+    // A stopped request reads the same whoever stopped it: 'Stopped', as
+    // jobFromRequest gives one seen by polling, with its step settled —
+    // never the surface's doneTitle over a pulsing step. The 0.3.x path
+    // closes the panel as it always did.
+    setState((s) => ({
+      ...s,
+      running: false,
+      finishedAt: new Date().toISOString(),
+      ...(live
+        ? {
+            status: "stopped",
+            queued: false,
+            needsYou: false,
+            error: "Stopped",
+            steps: (s.steps ?? []).map((x) => (x.status === "running" ? { ...x, status: "failed" } : x)),
+          }
+        : {}),
+    }));
+    if (live) return stopRequest(request.id);
+    if (pathRef.current === "legacy" && sessionRef.current) return cancelJob(sessionRef.current);
+    return undefined;
   }, []);
 
   const reset = useCallback(() => {
     abortRef.current?.abort();
+    followRef.current?.();
+    followRef.current = null;
+    pathRef.current = null;
     sessionRef.current = null;
+    requestRef.current = null;
+    movedRef.current = null;
     setState(IDLE);
   }, []);
 
-  return { ...state, start, cancel, reset };
+  // Take the founder to the conversation: the question when it needs
+  // them, the account of the work otherwise. False on the 0.3.x path.
+  const open = useCallback(() => (requestRef.current ? openRequest(requestRef.current) : false), []);
+
+  return { ...state, start, cancel, reset, open };
 }