makersclaw 0.8.0 → 0.8.2

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

@@ -1,16 +1,61 @@
 "use client";
 
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { claw, publishDesk, publishStatus } from "./claw";
-import { ask, cancelJob, llm, openRequest, requests as readRequests, startJob, stopRequest } from "./platform";
+import { claw, openApp, openConnections, openFile, pressMessage, publishDesk, publishStatus } from "./claw";
+import {
+  activity as readActivity,
+  agentKit as readAgentKit,
+  answer as sendAnswer,
+  approval as readApproval,
+  ask,
+  cancelJob,
+  connectLink,
+  connections as readConnections,
+  jobs as readJobs,
+  library,
+  llm,
+  llmEstimate,
+  openRequest,
+  pauseApp,
+  requests as readRequests,
+  resumeApp,
+  run as readRun,
+  runNow as startRun,
+  runs as readRuns,
+  saidSomething,
+  setJob,
+  startJob,
+  stopRequest,
+  streamThread,
+  thread as readThread,
+  threadCall as readThreadCall,
+  threads as readThreads,
+} 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
 // pixel. "use client" only: the _claw API is browser-side.
 //
-// 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 —
+// Up to 0.8.1 this header said there was no runs or activity hook here
+// and there would not be: those were STANDING surfaces, and the OS drew
+// them as tabs on the app window (docs/ARTIFACT-CONTRACTS.md §9) so that
+// every app showed its agent's work in one look. The kit (0.8.1, D15)
+// changed that. One look now lives in the kit's blocks, drawn in the
+// app's theme, so the app shows its agent's work itself, beside the rows
+// it wrote: `useJobs` (the schedule, Run now, the switches), `useRuns` and
+// `useRun` (the runs and one run's account), `useNeedsYou` (what waits on
+// this member), `useActivity` (who did what, a record's timeline),
+// `useConnections` (the app's accounts), `useAgentKit` (what its agent
+// knows and can do) and `useLlmAction` (a model call with its price
+// first). The OS tabs stay, as the full history; the yes, the account
+// sign-in and money stay on the desk. Each kit hook polls only while the
+// page is shown, backs off while its door is missing, aborts on unmount,
+// and never throws: a missing door is `unavailable`, a quiet "not
+// connected yet", never an error.
+//
+// The chat came first (0.8.1): `useAgentThread` follows the member's own
+// thread with the app's agent, the same conversation the desk's column
+// shows, for the `agent-chat` block. `useJob` is the other thing —
 // 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
@@ -19,7 +64,10 @@ import { ask, cancelJob, llm, openRequest, requests as readRequests, startJob, s
 // from a surface: the asks in flight on this app, so an empty table can
 // show the work coming instead of a blank. `useLlm` (0.8.0) is neither:
 // one call to a model, answered in the page, for text work on what the
-// screen holds — nothing to follow, nothing on the desk.
+// screen holds — nothing to follow, nothing on the desk. Nor are the
+// Library's hooks (0.8.1): they read the collections Makersclaw keeps,
+// once, when the screen asks (a collection's items and rows a page at a
+// time), and have nothing to poll.
 //
 // 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
@@ -698,7 +746,8 @@ const QUIET = { loading: false, result: null, error: null, unavailable: false };
  * { ok: false, aborted: true } and changes nothing, so a slow answer never
  * lands over a newer one. The hook owns the signal (one in opts is
  * replaced). Unmounting aborts the call in flight. Nothing is called until
- * `run` is.
+ * `run` is. `reset()` (0.8.1) clears what is shown and drops a call in
+ * flight.
  *
  *   const { run, loading, result, error, unavailable } = useLlm();
  *   run(`Translate to French: ${text}`, { task: "translate" });
@@ -739,5 +788,1625 @@ export function useLlm() {
     return answer;
   }, []);
 
-  return { ...state, run };
+  // Back to nothing shown: a call in flight is aborted and its answer
+  // changes nothing.
+  const reset = useCallback(() => {
+    abortRef.current?.abort();
+    runRef.current += 1;
+    setState(QUIET);
+  }, []);
+
+  return { ...state, run, reset };
+}
+
+// ---------------------------------------------------------------------------
+// The Library (0.8.1): lib/platform.js, library
+
+/** What a Library read shows while it is out, and what it shows with
+ *  nothing to read (no id yet, or `enabled` false). `key` names the read
+ *  the state belongs to: a state kept for another read is not shown. */
+const READING = { key: null, data: null, loading: true, error: null, code: null, unavailable: false };
+const NOTHING = { key: null, data: null, loading: false, error: null, code: null, unavailable: false };
+const NONE = [];
+
+/** A read that did not give the hooks an answer to hold: the platform's
+ *  refusal, a claw with no door, or an answer that is not the door's.
+ *  `unavailable` (a claw from before the door, or no network) leaves
+ *  `error` null, so a refusal and a missing door are never both set (as
+ *  useLlm). `code` is the refusal's (`needs_plan`), when it named one. */
+function unanswered(r) {
+  if (r.unavailable) return { error: null, code: null, unavailable: true };
+  return { error: r.error || "the Library did not answer", code: r.code ?? null, unavailable: false };
+}
+
+/** Is this a read the door answered with an object? A 200 of another kind
+ *  (a login page in front of the app) is not the Library's. */
+function answered(r) {
+  if (!r.ok) return r;
+  if (r.data && typeof r.data === "object" && !Array.isArray(r.data)) return r;
+  return { ok: false, status: r.status, error: "the platform answered something unexpected", unavailable: false };
+}
+
+/**
+ * One read of the Library, once: fetches when `key` changes (the key names
+ * the read: its id and its options) and on reload(). While the key is the
+ * same a failed reload keeps the last data and sets `error`; a new key
+ * shows `loading` and nothing else, never the last read's answer. Aborts a
+ * read it no longer wants. → { data, loading, error, code, unavailable,
+ * reload }
+ */
+function useLibraryRead(read, key, enabled) {
+  const [state, setState] = useState(READING);
+  const [tick, setTick] = useState(0);
+  const readRef = useRef(read);
+  readRef.current = read;
+  const reload = useCallback(() => setTick((t) => t + 1), []);
+
+  useEffect(() => {
+    if (!enabled) return undefined;
+    const controller = new AbortController();
+    let alive = true;
+    (async () => {
+      const r = answered(await readRef.current(controller.signal));
+      if (!alive || r.aborted) return;
+      if (r.ok) setState({ key, data: r.data, loading: false, error: null, code: null, unavailable: false });
+      else setState((s) => ({ key, data: s.key === key ? s.data : null, loading: false, ...unanswered(r) }));
+    })();
+    return () => {
+      alive = false;
+      controller.abort();
+    };
+  }, [key, enabled, tick]);
+
+  const mine = enabled ? (state.key === key ? state : READING) : NOTHING;
+  return { data: mine.data, loading: mine.loading, error: mine.error, code: mine.code, unavailable: mine.unavailable, reload };
+}
+
+/** A page's list, total and next cursor from a door's answer. */
+function pageOf(data, name) {
+  return {
+    list: Array.isArray(data?.[name]) ? data[name] : NONE,
+    total: typeof data?.total === "number" ? data.total : null,
+    previewOnly: Boolean(data?.preview_only),
+    next: typeof data?.next_cursor === "string" && data.next_cursor ? data.next_cursor : null,
+  };
+}
+
+const READING_PAGE = {
+  key: null,
+  list: NONE,
+  total: null,
+  previewOnly: false,
+  next: null,
+  loading: true,
+  loadingMore: false,
+  error: null,
+  code: null,
+  unavailable: false,
+};
+const NOTHING_PAGE = { ...READING_PAGE, loading: false };
+
+/**
+ * A collection's items or rows, a page at a time. `read(cursor, signal)`
+ * asks for one page. The first page is read when `key` changes and on
+ * reload(); loadMore() reads the one after it and adds it to the list (a
+ * row seen twice is kept once). A new key, a reload and an unmount abort a
+ * loadMore in flight, so a late page never lands on another list. →
+ * { list, total, previewOnly, hasMore, loading, loadingMore, error, code,
+ * unavailable, loadMore, reload }
+ */
+function useLibraryPage(name, read, key, enabled) {
+  const [state, setState] = useState(READING_PAGE);
+  const [tick, setTick] = useState(0);
+  const readRef = useRef(read);
+  readRef.current = read;
+  const nowRef = useRef({ key, state });
+  nowRef.current = { key, state };
+  const moreRef = useRef(null); // the loadMore in flight: its AbortController
+  const reload = useCallback(() => setTick((t) => t + 1), []);
+
+  useEffect(() => {
+    if (!enabled) return undefined;
+    const controller = new AbortController();
+    let alive = true;
+    (async () => {
+      const r = answered(await readRef.current(null, controller.signal));
+      if (!alive || r.aborted) return;
+      if (r.ok) setState({ ...READING_PAGE, ...pageOf(r.data, name), key, loading: false });
+      else setState((s) => ({ ...(s.key === key ? s : READING_PAGE), key, loading: false, loadingMore: false, ...unanswered(r) }));
+    })();
+    return () => {
+      alive = false;
+      controller.abort();
+      moreRef.current?.abort();
+      moreRef.current = null;
+    };
+  }, [name, key, enabled, tick]);
+
+  const loadMore = useCallback(async () => {
+    const { key: now, state: held } = nowRef.current;
+    if (held.key !== now || !held.next || moreRef.current) return undefined;
+    const controller = new AbortController();
+    moreRef.current = controller;
+    setState((s) => (s.key === now ? { ...s, loadingMore: true, error: null, code: null } : s));
+    const r = answered(await readRef.current(held.next, controller.signal));
+    if (moreRef.current === controller) moreRef.current = null;
+    if (controller.signal.aborted) return r; // a new key, a reload or an unmount took the list
+    setState((s) => {
+      if (s.key !== now) return s;
+      if (!r.ok) return { ...s, loadingMore: false, ...unanswered(r) };
+      const page = pageOf(r.data, name);
+      const seen = new Set(s.list.map((x) => x?.id));
+      return {
+        ...s,
+        list: [...s.list, ...page.list.filter((x) => !seen.has(x?.id))],
+        total: page.total ?? s.total,
+        previewOnly: page.previewOnly,
+        next: page.next,
+        loadingMore: false,
+        error: null,
+        code: null,
+        unavailable: false,
+      };
+    });
+    return r;
+  }, [name]);
+
+  const mine = enabled ? (state.key === key ? state : READING_PAGE) : NOTHING_PAGE;
+  return {
+    list: mine.list,
+    total: mine.total,
+    previewOnly: mine.previewOnly,
+    hasMore: Boolean(mine.next),
+    loading: mine.loading,
+    loadingMore: mine.loadingMore,
+    error: mine.error,
+    code: mine.code,
+    unavailable: mine.unavailable,
+    loadMore,
+    reload,
+  };
+}
+
+/** Filters as a key that does not depend on the order they were written
+ *  in: the ones with a value, sorted by column. */
+function filtersKey(filters) {
+  if (!filters || typeof filters !== "object" || Array.isArray(filters)) return [];
+  return Object.entries(filters)
+    .filter(([, v]) => (typeof v === "string" ? v.trim() !== "" : typeof v === "number" || typeof v === "boolean"))
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+}
+
+/**
+ * The collections on the Library's shelves (library.collections), for a
+ * screen that offers a choice. Read once; reload() reads again.
+ *
+ *   const { collections, loading, error, unavailable } = useLibraryCollections({ shelf: "decks" });
+ *
+ * → { collections, loading, error, code, unavailable, reload }. Each
+ * collection is a card: { id, slug, title, blurb, kind, shelf, tags,
+ * access, status, public_page, cover_url, item_count, row_count, usable,
+ * preview_only }. `enabled: false` reads nothing.
+ */
+export function useLibraryCollections(opts) {
+  const { q, shelf, enabled = true } = opts ?? {};
+  const key = JSON.stringify(["collections", q ?? "", shelf ?? ""]);
+  const { data, ...rest } = useLibraryRead((signal) => library.collections({ q, shelf, signal }), key, Boolean(enabled));
+  return { collections: Array.isArray(data?.collections) ? data.collections : NONE, ...rest };
+}
+
+/**
+ * One collection whole (library.collection): its card and `body`,
+ * `columns` (a rows collection's: { key, label, type, filter, … }),
+ * `source`, `licence`, `preview_count`, `personal_data`, `published_at`.
+ * `id` is its slug or uuid. Nothing is read until there is an id.
+ * → { collection, loading, error, code, unavailable, reload }
+ */
+export function useLibraryCollection(id, opts) {
+  const enabled = Boolean(id) && (opts?.enabled ?? true);
+  const key = JSON.stringify(["collection", id ?? null]);
+  const { data, ...rest } = useLibraryRead((signal) => library.collection(id, { signal }), key, enabled);
+  return { collection: data?.collection ?? null, ...rest };
+}
+
+/**
+ * A files collection's items, a page at a time (library.items):
+ *
+ *   const { items, total, previewOnly, hasMore, loadMore, loading, loadingMore } =
+ *     useLibraryItems("pitch-decks", { q: search, tag: "seed", limit: 24 });
+ *
+ *   items         the pages read so far, in the Library's order
+ *   total         how many there are in all (null before the first page);
+ *                 on a preview, the true count, not the count shown
+ *   previewOnly   a paid collection on a Free plan: `items` are the
+ *                 preview's only (the ones past it are not listed, and
+ *                 useLibraryItem on one says `needs_plan`)
+ *   hasMore       loadMore() has a page to read
+ *   loading       the first page is out    loadingMore   a later one is
+ *   error, code, unavailable              as for every Library hook
+ *   loadMore()    reads the next page and adds it; nothing when there is
+ *                 none, or while one is out
+ *   reload()      reads the first page again
+ *
+ * A new `id`, `q`, `tag` or `limit` starts the list over (a `q` typed key
+ * by key should be debounced by the screen). Nothing is read until there
+ * is an id.
+ */
+export function useLibraryItems(id, opts) {
+  const { q, tag, limit, enabled = true } = opts ?? {};
+  const key = JSON.stringify(["items", id ?? null, q ?? "", tag ?? "", limit ?? null]);
+  const { list, ...rest } = useLibraryPage(
+    "items",
+    (cursor, signal) => library.items(id, { q, tag, limit, cursor, signal }),
+    key,
+    Boolean(id) && Boolean(enabled),
+  );
+  return { items: list, ...rest };
+}
+
+/**
+ * A rows collection's rows, a page at a time (library.rows): the same
+ * state as useLibraryItems, with `rows` ({ id, data, source_url }) in
+ * place of `items`. `filters` is { <column key>: value }, for the columns
+ * the collection marks as filters; a value that is empty is left out, and
+ * the order they are written in does not matter. An `image` cell of a
+ * row's `data` is a signed address, good for ten minutes: reload() to
+ * read the page again when the screen has been open longer.
+ */
+export function useLibraryRows(id, opts) {
+  const { q, filters, limit, enabled = true } = opts ?? {};
+  const key = JSON.stringify(["rows", id ?? null, q ?? "", filtersKey(filters), limit ?? null]);
+  const { list, ...rest } = useLibraryPage(
+    "rows",
+    (cursor, signal) => library.rows(id, { q, filters, limit, cursor, signal }),
+    key,
+    Boolean(id) && Boolean(enabled),
+  );
+  return { rows: list, ...rest };
+}
+
+/**
+ * One item (library.item): the card's fields as `item`, its file's signed
+ * address as `fileUrl` (good for ten minutes: show or download from it,
+ * never keep it; reload() signs another) and the first 4,000 characters of
+ * its text as `textExcerpt`. An item the member's plan does not open is
+ * `code: "needs_plan"` with the platform's words in `error`, and no
+ * `fileUrl`. Nothing is read until there is an id.
+ * → { item, fileUrl, textExcerpt, loading, error, code, unavailable, reload }
+ */
+export function useLibraryItem(id, opts) {
+  const enabled = Boolean(id) && (opts?.enabled ?? true);
+  const key = JSON.stringify(["item", id ?? null]);
+  const { data, ...rest } = useLibraryRead((signal) => library.item(id, { signal }), key, enabled);
+  return { item: data?.item ?? null, fileUrl: data?.file_url ?? null, textExcerpt: data?.text_excerpt ?? null, ...rest };
+}
+
+// ---------------------------------------------------------------------------
+// The app's own chat (0.8.1)
+
+/** How often the chat looks while the agent works, and while it waits on
+ *  the member on the desk. Nothing is polled once a turn has ended. */
+const CHAT_WORKING_MS = 1500;
+const CHAT_WAITING_MS = 6000;
+/** Where the chat keeps its thread for a key (`<kind>:<id>`, or "app"),
+ *  so the person's chat is there again when the person is opened again.
+ *  This browser's only; the platform keeps the thread itself. */
+const CHAT_KEY = "claw.chat.";
+
+function keptThread(key) {
+  if (!key) return null;
+  try {
+    return localStorage.getItem(CHAT_KEY + key) || null;
+  } catch {
+    return null;
+  }
+}
+
+// Who else reads the same thread in this page, so a reader that was not the
+// one to start it follows it (2026-10-12): the agent's dock keeps its pane
+// mounted beside the work, and a button on a screen, the Today ask bar and
+// the dock are each a useAgentThread on the same key. `from` is the reader
+// that made the change; it does not hear itself.
+const THREAD_KEPT = "claw:thread-kept";
+
+function keepThread(key, sessionId, from) {
+  if (!key) return;
+  try {
+    if (sessionId) localStorage.setItem(CHAT_KEY + key, sessionId);
+    else localStorage.removeItem(CHAT_KEY + key);
+  } catch {
+    /* private mode: the chat starts fresh next time */
+  }
+  try {
+    window.dispatchEvent(new CustomEvent(THREAD_KEPT, { detail: { key, sessionId: sessionId || null, from } }));
+  } catch {
+    /* no window: nobody else is reading */
+  }
+}
+
+const CHAT_LIVE = new Set(["queued", "working"]);
+
+// A pending question is identified by its request and input ids, not the
+// time its GET/stream frame arrived. Accepted answers must not reappear
+// while the agent resumes, and a genuinely new question must still show.
+function threadQuestionKey(data) {
+  if (data?.state !== "needs_you" || data.needs?.kind !== "question") return null;
+  const ids = (data.view?.questions ?? []).map((q) => q.id).filter(Boolean).sort();
+  return JSON.stringify([data.session_id, data.request?.id, data.needs.at ?? null, ids, ids.length ? null : data.needs.text]);
+}
+
+function withoutThreadQuestion(data) {
+  return { ...data, state: "working", needs: null, ...(data.view ? { view: { ...data.view, questions: [], thinking: true } } : {}) };
+}
+
+
+/**
+ * The member's own thread with the app's agent, for the app's own chat
+ * (the `agent-chat` block): the same eve session the desk's agent column
+ * shows — one conversation, two views, never a copy.
+ *
+ *   const chat = useAgentThread({ row: { kind: "person", id, name } });
+ *   <AgentChat chat={chat} title={`Ask about ${name}`} />
+ *
+ * Options (all optional):
+ *   row       the record the chat is about ({ kind, id, name }): it rides
+ *             with every ask as context, and the thread is kept for it
+ *   how       instructions for the agent only (the AGENTS.md section)
+ *   job       a declared job's key, or true; by default none — a chat is
+ *             a conversation, not a job
+ *   key       where this browser keeps the thread (default `<kind>:<id>`
+ *             of the row, else "app"); null keeps none
+ *             Readers on the same key in one page follow each other: one that
+ *             starts, drops or switches the thread is heard by the rest (the
+ *             dock's pane, the Today ask bar and a screen's buttons share it)
+ *   view      true asks the door for the thread as the desk's sidebar draws
+ *             it (0.8.1, D27: the `agent-pane` block; useAgentPane sets it)
+ *
+ * State:
+ *   sessionId   the thread, or null before the first ask
+ *   state       queued | working | needs_you | done | stopped | failed, or
+ *               null before the first ask
+ *   needs       { kind, text, at, in_app, options?, free? } while it waits
+ *               on the member. `in_app` is how the app can settle it:
+ *               "answer" (a question: answer({ optionId | text }), with
+ *               its `options` and whether `free` words are welcome),
+ *               "press" (the one ask's yes: the `approval` block's press
+ *               frame, useApproval(request.id)), or null (on the desk:
+ *               openOnDesk)
+ *   turns       [{ id, member, parts: [{ type: "text", text } |
+ *               { type: "step", label, status }], writing, status }]
+ *   pending     the member's words just sent, until the thread has them
+ *   view        with `view: true`, the sidebar's view: { messages, thinking,
+ *               failure, questions } (platform.js thread), else null
+ *   sameConversation  the next message continues this request (D29: also
+ *               after a Stop, a finish or a failed turn); false for a plan,
+ *               a piece, a change sent up, a counted job (a new request)
+ *   place       "app", or "makersclaw" for an ask made in Makersclaw (the
+ *               chat shows a pointer, not the turns)
+ *   request     the request the thread is on (as useRequests reads one)
+ *   sending, loading, error, code, unavailable (a claw with no door yet)
+ *
+ * Actions: send(text, { files }) · stop() · answer({ optionId, text } | { answers }) ·
+ * openOnDesk() · newChat() · openSession(sessionId) · reload(). answer is
+ * the agent's question answered in the chat where it was asked (0.8.1,
+ * D19): → { ok } | { ok: false, error, code }. `answers` is
+ * [{ requestId, optionId | text }], one per question `view.questions`
+ * lists, sent as one resume (D27). openSession switches to another of the
+ * member's threads (the pane's Chats list). `files` are [{ name, type, data }]
+ * (data URLs, at most 4 and 3 MB together) sent with the words (D27 phase 4);
+ * `notice` says when they did not go (the ask is queued). With `view: true`
+ * a working thread is streamed (platform.js streamThread) and polled as the
+ * safety net.
+ * send continues the thread (ask({ sessionId })) — after a Stop, a finish
+ * or a failed turn too: the platform opens the closed request again, in the
+ * same session, so there is no new card (D29) — and starts a fresh one only
+ * when the old one is a teammate's or gone. The desk's column is never
+ * opened by an ask from here (`open: false`); openOnDesk is the member's
+ * press, and opens it.
+ */
+export function useAgentThread({ row, how, job = false, key, view = false } = {}) {
+  const storeKey = key === null ? null : (key ?? (row?.kind && row?.id ? `${row.kind}:${row.id}` : "app"));
+  const [sessionId, setSessionId] = useState(() => keptThread(storeKey));
+  const me = useRef({}).current;
+  const [state, setState] = useState({
+    data: null,
+    loading: Boolean(sessionId),
+    sending: false,
+    pending: null,
+    error: null,
+    code: null,
+    unavailable: false,
+  });
+  const [tick, setTick] = useState(0);
+  const reload = useCallback(() => setTick((t) => t + 1), []);
+  const aliveRef = useRef(true);
+  const dataRef = useRef(state.data);
+  dataRef.current = state.data;
+  const dismissedQuestions = useRef(new Map());
+  const protectQuestions = (data) => dismissedQuestions.current.has(threadQuestionKey(data)) ? withoutThreadQuestion(data) : data;
+  const dismissQuestion = () => {
+    const snapshot = dataRef.current;
+    const questionKey = threadQuestionKey(snapshot);
+    if (!questionKey) return null;
+    const pending = { key: questionKey, snapshot };
+    dismissedQuestions.current.set(questionKey, pending);
+    setState((s) => ({ ...s, error: null, data: protectQuestions(s.data) }));
+    return pending;
+  };
+  const restoreQuestion = (pending, error) => {
+    if (!pending || dismissedQuestions.current.get(pending.key) !== pending) return;
+    dismissedQuestions.current.delete(pending.key);
+    const before = pending.snapshot;
+    setState((s) => {
+      const current = s.data;
+      const otherQuestion = threadQuestionKey(current);
+      if (!current || current.session_id !== before.session_id || current.request?.id !== before.request?.id || (otherQuestion && otherQuestion !== pending.key)) return s;
+      return { ...s, error, data: { ...current, state: before.state, needs: before.needs, ...(before.view ? { view: { ...current.view, questions: before.view.questions, thinking: before.view.thinking } } : {}) } };
+    });
+  };
+  const confirmQuestion = (pending) => { if (pending) pending.snapshot = null; };
+  const sessionRef = useRef(sessionId);
+  sessionRef.current = sessionId;
+  const rowRef = useRef(row);
+  rowRef.current = row;
+  const viewRef = useRef(view);
+  viewRef.current = view;
+  // Words sent and not in the thread yet: the agent's turn has not opened,
+  // so the chat keeps looking (for a minute at most) though the last turn
+  // has ended.
+  const pendingRef = useRef(null);
+  pendingRef.current = state.pending ? (pendingRef.current?.words === state.pending ? pendingRef.current : { words: state.pending, at: Date.now() }) : null;
+
+  useEffect(() => {
+    aliveRef.current = true;
+    return () => {
+      aliveRef.current = false;
+    };
+  }, []);
+
+  // Another record opened in the same chat: its own thread.
+  const lastKey = useRef(storeKey);
+  useEffect(() => {
+    if (lastKey.current === storeKey) return;
+    lastKey.current = storeKey;
+    const kept = keptThread(storeKey);
+    dismissedQuestions.current.clear();
+    setSessionId(kept);
+    setState({ data: null, loading: Boolean(kept), sending: false, pending: null, error: null, code: null, unavailable: false });
+  }, [storeKey]);
+
+  // Another reader of this thread started it, dropped it or opened another
+  // chat in it: follow (a pane that stays mounted beside the work, the Today
+  // ask bar, a button on a screen). The one that made the change does not
+  // hear itself.
+  useEffect(() => {
+    if (!storeKey || typeof window === "undefined" || typeof window.addEventListener !== "function") return undefined;
+    const on = (e) => {
+      const d = e.detail;
+      if (!d || d.key !== storeKey || d.from === me) return;
+      const next = d.sessionId ?? null;
+      if (next === sessionRef.current) return;
+      dismissedQuestions.current.clear();
+      setSessionId(next);
+      setState({ data: null, loading: Boolean(next), sending: false, pending: null, error: null, code: null, unavailable: false });
+    };
+    window.addEventListener(THREAD_KEPT, on);
+    return () => window.removeEventListener(THREAD_KEPT, on);
+  }, [storeKey, me]);
+
+  const forget = useCallback(() => {
+    keepThread(storeKey, null, me);
+    setSessionId(null);
+  }, [storeKey, me]);
+
+  // Follow the thread: at once, then while the agent works or waits. With
+  // the sidebar's view (the `agent-pane` block) a working thread is also
+  // STREAMED (0.8.1, D27 phase 4): the gateway pushes the thread after each
+  // burst of the agent's events, so text and steps appear as they happen.
+  // The poll stays as the safety net: it looks every few seconds while the
+  // stream is alive and takes over when it ends, breaks, or does not exist.
+  useEffect(() => {
+    if (!sessionId) return undefined;
+    const controller = new AbortController();
+    let alive = true;
+    let timer = null;
+    let inflight = false;
+    let streaming = false;
+    let streamOff = false;
+    let quickEnds = 0;
+    let lastLine = 0;
+    let streamStop = null;
+    const schedule = (ms) => {
+      clearTimeout(timer);
+      timer = null;
+      if (alive && ms && screen.shown()) timer = setTimeout(load, ms);
+    };
+    const wordsLanded = (data, words) =>
+      Boolean(words) && ((data.turns ?? []).some((t) => t.member === words) || (data.view?.messages ?? []).some((m) => m.role === "user" && m.text === words));
+    const applyFrame = (frame) => {
+      if (!alive) return;
+      if (frame.desk_origin) publishDesk(frame.desk_origin);
+      setState((s) => ({
+        ...s,
+        data: protectQuestions({ ...(s.data ?? {}), ...frame, turns: s.data?.turns ?? [] }),
+        loading: false,
+        error: null,
+        code: null,
+        unavailable: false,
+        pending: wordsLanded(frame, s.pending) ? null : s.pending,
+      }));
+    };
+    const openStream = () => {
+      if (!viewRef.current || streaming || streamOff || !alive || !screen.shown()) return;
+      streaming = true;
+      lastLine = Date.now();
+      const began = Date.now();
+      const stop = new AbortController();
+      streamStop = stop;
+      // No line (not even a ping) for 25 s: the stream is dead, not quiet.
+      const watchdog = setInterval(() => {
+        if (Date.now() - lastLine > 25000) stop.abort();
+      }, 5000);
+      streamThread(sessionId, { signal: stop.signal, onLine: () => (lastLine = Date.now()), onThread: applyFrame }).then((r) => {
+        clearInterval(watchdog);
+        streaming = false;
+        streamStop = null;
+        if (!alive) return;
+        // A claw with no stream, or a thread it will not stream: poll.
+        if (!r.ok && !r.aborted && (r.unavailable || r.status === 404 || r.status === 403)) streamOff = true;
+        // Three streams in a row that ended at once: stop trying.
+        quickEnds = Date.now() - began < 2000 ? quickEnds + 1 : 0;
+        if (quickEnds >= 3) streamOff = true;
+        load(); // the canonical read, and a new stream if it is still going
+      });
+    };
+    const load = async () => {
+      clearTimeout(timer);
+      timer = null;
+      if (!alive || inflight || !screen.shown()) return;
+      // While a stream is alive it is the fresher view: look rarely.
+      if (streaming && Date.now() - lastLine < 20000) {
+        schedule(CHAT_WORKING_MS * 3);
+        return;
+      }
+      inflight = true;
+      const r = await readThread(sessionId, { signal: controller.signal, view: viewRef.current });
+      inflight = false;
+      if (!alive || r.aborted) return;
+      if (r.ok && r.data) {
+        const data = r.data;
+        if (data.desk_origin) publishDesk(data.desk_origin);
+        setState((s) => ({
+          ...s,
+          data: protectQuestions(data),
+          loading: false,
+          error: null,
+          code: null,
+          unavailable: false,
+          pending: wordsLanded(data, s.pending) ? null : s.pending,
+        }));
+        const turns = data.turns ?? [];
+        const last = turns[turns.length - 1];
+        const waitingForTurn = pendingRef.current && Date.now() - pendingRef.current.at < 60000;
+        const working = CHAT_LIVE.has(data.state) || last?.status === "working" || Boolean(waitingForTurn);
+        if (working && CHAT_LIVE.has(data.state)) openStream();
+        schedule(working ? CHAT_WORKING_MS : data.state === "needs_you" ? CHAT_WAITING_MS : 0);
+        return;
+      }
+      if (r.status === 403 || r.status === 404) {
+        if (r.code) {
+          // A teammate's thread, or one this app no longer has: start fresh.
+          forget();
+          setState((s) => ({ ...s, data: null, loading: false }));
+          return;
+        }
+        setState((s) => ({ ...s, loading: false, unavailable: true }));
+        return;
+      }
+      setState((s) => ({ ...s, loading: false, error: r.error ?? null }));
+      schedule(CHAT_WORKING_MS * 4); // a blip: look again, a little later
+    };
+    const screen = watchShown(load);
+    load();
+    return () => {
+      alive = false;
+      controller.abort();
+      streamStop?.abort();
+      clearTimeout(timer);
+      screen.stop();
+    };
+  }, [sessionId, tick, forget]);
+
+  const send = useCallback(
+    async (message, { files } = {}) => {
+      const text = String(message ?? "").trim();
+      if (!text) return { ok: false, error: "nothing to ask" };
+      const dismissed = dismissQuestion();
+      setState((s) => ({ ...s, sending: true, pending: text, error: null, code: null, notice: null }));
+      const asking = (session) =>
+        ask({ text, row: rowRef.current ?? undefined, how, job, files, sessionId: session ?? undefined, open: false });
+      let result = await asking(sessionRef.current);
+      if (!result.ok && sessionRef.current && START_FRESH.has(result.code)) result = await asking(null);
+      if (!aliveRef.current) return result;
+      if (!result.ok) {
+        restoreQuestion(dismissed, result.error ?? "The ask could not be sent.");
+        const unavailable = result.status === 404 && !result.code;
+        setState((s) => ({
+          ...s,
+          sending: false,
+          pending: null,
+          error: unavailable ? null : (result.error ?? "The ask could not be sent."),
+          code: result.code ?? null,
+          unavailable: unavailable || s.unavailable,
+        }));
+        return result;
+      }
+      confirmQuestion(dismissed);
+      announceAsk();
+      const request = result.data?.request ?? null;
+      const next = request?.app_session_id ?? sessionRef.current ?? null;
+      if (next) {
+        keepThread(storeKey, next, me);
+        if (next !== sessionRef.current) setSessionId(next);
+        else reload();
+      }
+      setState((s) => ({
+        ...s,
+        sending: false,
+        // The ask was taken but waits its turn: a file is not kept for later.
+        notice:
+          result.data?.files_attached === false
+            ? "Your files did not go with that message because it is waiting its turn. Attach them again once it starts."
+            : null,
+        data: s.data && next === s.data.session_id ? (threadQuestionKey(s.data) && threadQuestionKey(s.data) !== dismissed?.key ? s.data : { ...s.data, state: "working", request: request ?? s.data.request }) : s.data,
+      }));
+      return result;
+    },
+    [how, job, storeKey, reload, me],
+  );
+
+  const request = state.data?.request ?? null;
+  const stop = useCallback(async () => {
+    if (!request?.id) return { ok: false, error: "nothing to stop" };
+    const r = await stopRequest(request.id);
+    reload();
+    return r;
+  }, [request?.id, reload]);
+  const needsAt = state.data?.needs?.at ?? null;
+  const answer = useCallback(
+    async ({ optionId, text, answers } = {}) => {
+      if (!request?.id) return { ok: false, error: "nothing to answer" };
+      const dismissed = dismissQuestion();
+      const r = await sendAnswer(request.id, { optionId, text, answers, at: needsAt ?? undefined });
+      if (!aliveRef.current) return r.ok ? { ok: true } : { ok: false, error: r.error, code: r.code ?? null };
+      if (!r.ok) restoreQuestion(dismissed, r.error ?? "That answer did not go through. Try again.");
+      if (r.ok) {
+        confirmQuestion(dismissed);
+        announceAsk();
+        setState((s) => ({ ...s, error: null }));
+      }
+      if (r.ok) reload();
+      return r.ok ? { ok: true } : { ok: false, error: r.error, code: r.code ?? null };
+    },
+    [request?.id, needsAt, reload],
+  );
+  const openOnDesk = useCallback(() => (request ? openRequest(request) : false), [request]);
+  const newChat = useCallback(() => {
+    forget();
+    dismissedQuestions.current.clear();
+    setState({ data: null, loading: false, sending: false, pending: null, error: null, code: null, unavailable: false });
+  }, [forget]);
+  // Another of the member's threads in this app (the pane's Chats list):
+  // kept as this chat's, so the same record opens on it next time.
+  const openSession = useCallback(
+    (next) => {
+      const id = typeof next === "string" && next ? next : null;
+      if (!id || id === sessionRef.current) return;
+      dismissedQuestions.current.clear();
+      keepThread(storeKey, id, me);
+      setSessionId(id);
+      setState({ data: null, loading: true, sending: false, pending: null, error: null, code: null, unavailable: false });
+    },
+    [storeKey, me],
+  );
+
+  const data = state.data;
+  return {
+    sessionId,
+    state: data?.state ?? (state.sending ? "working" : null),
+    needs: data?.needs ?? null,
+    turns: data?.turns ?? [],
+    view: data?.view ?? null,
+    // Does the next message go on in this same request (D29)? True while it
+    // is open and after a Stop, a finish or a failed turn (the platform
+    // opens the closed request again, in the same session), false only for
+    // a plan or a piece of one, a change sent up, a counted job and a
+    // hand-off never started: those get a new request. Unknown (an older
+    // claw, or before the first read): true.
+    sameConversation: data?.same_conversation ?? true,
+    place: data?.thread ?? "app",
+    request,
+    pending: state.pending,
+    sending: state.sending,
+    loading: state.loading,
+    error: state.error,
+    code: state.code,
+    // A line to show beside the thread (files that did not go), or null.
+    notice: state.notice ?? null,
+    unavailable: state.unavailable,
+    send,
+    stop,
+    answer,
+    openOnDesk,
+    newChat,
+    openSession,
+    reload,
+  };
 }
+
+/** How often the Chats list looks while a thread is going, and otherwise. */
+const CHATS_WORKING_MS = 6000;
+const CHATS_IDLE_MS = 30000;
+
+/** A thread's request status as the Chats list marks it: waiting on the
+ *  member, or the agent is on it. */
+function chatMark(status) {
+  if (status === "needs_you") return "needs";
+  if (status === "queued" || status === "routing" || status === "installing" || status === "setting_up" || status === "building" || status === "working") return "working";
+  return null;
+}
+
+/**
+ * The member's own threads in this app, newest first, for the `agent-pane`
+ * block's Chats list (GET _claw/threads, 0.8.1, D27):
+ *
+ *   const { items, loading, error, unavailable } = useThreadList();
+ *
+ *   items  [{ sessionId, requestId, title, mark: "needs" | "working" | null, at }]
+ *
+ * Looks every 30 s, every 6 s while one is going or waits, and at once
+ * when an ask is sent. A claw from before the door is `unavailable`: the
+ * pane draws no list.
+ */
+export function useThreadList({ every = CHATS_IDLE_MS } = {}) {
+  const watched = useWatched((signal) => readThreads({ signal }), "threads", {
+    next: (data) => (listOf(data?.threads).some((t) => chatMark(t?.status)) ? CHATS_WORKING_MS : every),
+    listen: onAsked,
+  });
+  const items = useMemo(
+    () =>
+      listOf(watched.data?.threads)
+        .filter((t) => t && typeof t.session_id === "string")
+        .map((t) => ({
+          sessionId: t.session_id,
+          requestId: t.request_id ?? null,
+          title: typeof t.title === "string" && t.title.trim() ? t.title.trim() : "Untitled",
+          mark: chatMark(t.status),
+          at: t.updated_at ?? null,
+        })),
+    [watched.data],
+  );
+  return { items, loading: watched.loading, error: watched.error, unavailable: watched.unavailable, reload: watched.reload };
+}
+
+/**
+ * The desk's agent sidebar, as the app's own pane (0.8.1, D27; the
+ * `agent-pane` block). useAgentThread with the sidebar's view, plus what
+ * the sidebar has around its chat:
+ *
+ *   const chat = useAgentPane({ row: { kind: "person", id, name } });
+ *   <AgentPane chat={chat} title={`Ask about ${name}`} />
+ *
+ * Everything useAgentThread returns (`view` is set), and
+ *
+ *   chats        { items, loading, error, unavailable }: the member's
+ *                threads in this app (useThreadList); openSession(id)
+ *                switches to one
+ *   callDetail   (callId) → Promise<{ ok, call }>: one step of this
+ *                thread, opened (platform.js threadCall); the pane asks it
+ *                when a member opens a step
+ *   openRequest  (requestId): opens a request's thread on the desk
+ *   open         ({ kind: "app", id } | { kind: "file", path, where,
+ *                appRef }): opens an app or a file it made on the desk
+ *                (the pane's default "Open")
+ *
+ * Options are useAgentThread's: `row` (the record on screen, kept as that
+ * record's own thread), `how` (for the agent only), `job`, `key`.
+ */
+export function useAgentPane(options = {}) {
+  const chat = useAgentThread({ ...options, view: true });
+  const list = useThreadList();
+  const sessionId = chat.sessionId;
+  const callDetail = useCallback(
+    (callId) => (sessionId ? readThreadCall(sessionId, callId) : Promise.resolve({ ok: false, status: 0, error: "no thread", unavailable: false })),
+    [sessionId],
+  );
+  return {
+    ...chat,
+    chats: { items: list.items, loading: list.loading, error: list.error, unavailable: list.unavailable },
+    callDetail,
+    // "Open in Makersclaw" under a change the agent sent up: the desk opens
+    // that request's thread (a member's press).
+    openRequest: (id) => openRequest(id),
+    // "Open" under an app or a file the agent made (D27 phase 4): the desk
+    // opens it, on the member's press. → true when the desk was asked.
+    open: (target) => (target?.kind === "app" ? openApp(target.id) : target?.kind === "file" ? openFile(target) : false),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The kit (0.8.1, D15): the app shows its agent's work itself. Each hook
+// feeds one or more of the kit's blocks; the blocks take the hook's
+// answer as props and never read a door themselves.
+
+/** What a kit read shows before its first answer, and with nothing to
+ *  read (`enabled` false, no id). `key` names the read the state belongs
+ *  to: a state kept for another read is not shown. */
+const WATCH_READING = { key: null, data: null, loading: true, error: null, code: null, unavailable: false };
+const WATCH_NOTHING = { ...WATCH_READING, loading: false };
+
+/**
+ * One kit 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). Hidden, nothing is asked; coming back looks at once. A missing
+ * door (`unavailable`) is looked at once a minute and leaves `error`
+ * null; a refusal keeps the last answer and sets `error` and `code`. A
+ * `listen` subscription (onAsked) makes it look at once. Aborts what is
+ * out on unmount and when the key changes.
+ *   → { data, loading, error, code, unavailable, reload }
+ */
+function useWatched(read, key, { enabled = true, next, listen } = {}) {
+  const [state, setState] = useState(WATCH_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);
+    const unsubscribe = listen ? listen(load) : null;
+    load();
+    return () => {
+      alive = false;
+      controller.abort();
+      clearTimeout(timer);
+      screen.stop();
+      unsubscribe?.();
+    };
+  }, [key, enabled, tick]);
+
+  const mine = enabled ? (state.key === key ? state : WATCH_READING) : WATCH_NOTHING;
+  return { data: mine.data, loading: mine.loading, error: mine.error, code: mine.code, unavailable: mine.unavailable, reload };
+}
+
+/** How often useRuns and useJobs look while a run is going. */
+const RUNNING_MS = 5000;
+/** How often useRun looks at a run that is going. */
+const RUN_FOLLOW_MS = 2500;
+/** How often useConnections looks while an account is being connected,
+ *  and for how long. */
+const CONNECTING_MS = 3000;
+const CONNECTING_FOR_MS = 120000;
+
+const NO_MAY = Object.freeze({ run: false, switch: false, pause: false });
+const listOf = (value) => (Array.isArray(value) ? value : NONE);
+
+/**
+ * The app's declared jobs (its schedule), for the `schedule-card` and
+ * `workflow-view` blocks (GET _claw/jobs):
+ *
+ *   const { jobs, app, budget, may, busy, runNow, setEnabled } = useJobs();
+ *
+ *   jobs      [{ id, name, kind, topic, does, cron, tz, words, enabled,
+ *               next_run_at, last_run_at, last_run, plan }]
+ *   app       { status, live } or null: live is the app's Live switch
+ *   budget    { week_cap_credits, week_used_credits } or null (no cap)
+ *   credits   the workspace's credits, as _claw/me gives them, or null
+ *   may       { run, switch, pause }: what this member may press. Hide a
+ *             control they may not; the door refuses it anyway
+ *   busy      { [job id]: "run" | "switch" } while a press is out
+ *   appBusy   "pause" | "resume" while the Live switch's press is out
+ *   loading, error, code, unavailable, reload
+ *
+ * Actions, each resolving the platform call's answer and looking again
+ * after: runNow(id) (spends: show its price on the button), setEnabled(id,
+ * on), pause(), resume(). Looks every `every` ms (30 s), every 5 s while
+ * a job's last run is going.
+ */
+export function useJobs({ every = 30000 } = {}) {
+  const watched = useWatched((signal) => readJobs({ signal }), "jobs", {
+    next: (data) => (listOf(data?.jobs).some((j) => j?.last_run?.status === "running") ? RUNNING_MS : every),
+    listen: onAsked,
+  });
+  const { data, reload } = watched;
+  const [busy, setBusy] = useState({});
+  const [appBusy, setAppBusy] = useState(null);
+  const [patched, setPatched] = useState({}); // jobs as a switch's answer gave them, until the next read
+  const aliveRef = useRef(true);
+  useEffect(() => {
+    aliveRef.current = true;
+    return () => {
+      aliveRef.current = false;
+    };
+  }, []);
+  useEffect(() => setPatched((p) => (Object.keys(p).length ? {} : p)), [data]);
+
+  const mark = useCallback((id, what) => {
+    if (!aliveRef.current) return;
+    setBusy((b) => {
+      const nextBusy = { ...b };
+      if (what) nextBusy[id] = what;
+      else delete nextBusy[id];
+      return nextBusy;
+    });
+  }, []);
+
+  const runNow = useCallback(
+    async (id) => {
+      mark(id, "run");
+      const r = await startRun(id);
+      mark(id, null);
+      if (r.ok) announceAsk(); // the requests and the runs on the page look at once
+      if (aliveRef.current) reload();
+      return r;
+    },
+    [mark, reload],
+  );
+
+  const setEnabled = useCallback(
+    async (id, on) => {
+      mark(id, "switch");
+      const r = await setJob(id, { enabled: Boolean(on) });
+      mark(id, null);
+      if (!aliveRef.current) return r;
+      if (r.ok && r.data?.job?.id) setPatched((p) => ({ ...p, [r.data.job.id]: r.data.job }));
+      reload();
+      return r;
+    },
+    [mark, reload],
+  );
+
+  const live = useCallback(
+    async (on) => {
+      setAppBusy(on ? "resume" : "pause");
+      const r = await (on ? resumeApp() : pauseApp());
+      if (!aliveRef.current) return r;
+      setAppBusy(null);
+      reload();
+      return r;
+    },
+    [reload],
+  );
+  const pause = useCallback(() => live(false), [live]);
+  const resume = useCallback(() => live(true), [live]);
+
+  const jobs = useMemo(() => listOf(data?.jobs).map((j) => (j && patched[j.id] ? { ...j, ...patched[j.id] } : j)), [data, patched]);
+  return {
+    jobs,
+    app: data?.app ?? null,
+    budget: data?.budget ?? null,
+    credits: data?.credits ?? null,
+    may: data?.may ? { ...NO_MAY, ...data.may } : NO_MAY,
+    busy,
+    appBusy,
+    loading: watched.loading,
+    error: watched.error,
+    code: watched.code,
+    unavailable: watched.unavailable,
+    reload,
+    runNow,
+    setEnabled,
+    pause,
+    resume,
+  };
+}
+
+/**
+ * The app's runs, newest first, and their overview, for the `run-history`
+ * and `workflow-view` blocks (GET _claw/runs):
+ *
+ *   const { runs, overview } = useRuns({ job: wakeId, limit: 20 });
+ *
+ *   runs      [{ id, title, state, wake_id, job, trigger, by, number,
+ *               started_at, ended_at, duration_ms, credits, report, status }]
+ *             `state` is running | done | failed | stopped | needs_you
+ *   overview  { completed, failed, running, avg_ms, credits_week,
+ *               cap_week_credits } or null
+ *   loading, error, code, unavailable, reload
+ *
+ * `job` narrows to one job (its wake id), `limit` (20, at most 60). The
+ * jobs' runs and the member's own asks, never a teammate's ask. Looks
+ * every 5 s while a run is going, else every `every` ms (30 s), and at
+ * once after useJobs' Run now.
+ */
+export function useRuns({ job, limit = 20, every = 30000 } = {}) {
+  const key = JSON.stringify(["runs", job ?? null, limit ?? null]);
+  const watched = useWatched((signal) => readRuns({ job, limit, signal }), key, {
+    next: (data) => (listOf(data?.runs).some((r) => r?.state === "running") ? RUNNING_MS : every),
+    listen: onAsked,
+  });
+  const { data, ...rest } = watched;
+  return { runs: listOf(data?.runs), overview: data?.overview ?? null, ...rest };
+}
+
+/**
+ * One run's account, for the `run-history` block's RunAccount and the
+ * `workflow-view` graph (GET _claw/runs/<id>):
+ *
+ *   const { run, steps, text, needs } = useRun(selectedId);
+ *
+ *   run     the run, as useRuns lists it, or null
+ *   steps   [{ label, status: running | done | failed }], in order
+ *   text    the agent's report, or null
+ *   needs   { kind, text } while it waits on the member (answered on the
+ *           desk), or null
+ *
+ * Nothing is read while `id` is empty. Looks every 2.5 s while the run is
+ * going; a run that has ended is read once.
+ */
+export function useRun(id) {
+  const enabled = Boolean(id);
+  const watched = useWatched((signal) => readRun(id, { signal }), JSON.stringify(["run", id ?? null]), {
+    enabled,
+    next: (data) => (data?.run?.state === "running" ? RUN_FOLLOW_MS : 0),
+  });
+  const { data, ...rest } = watched;
+  return { run: data?.run ?? null, steps: listOf(data?.steps), text: data?.text ?? null, needs: data?.needs ?? null, ...rest };
+}
+
+/** A request's needs as a needs-you item's kind: the yes (an approval is
+ *  one), a question, a spend (a limit), a connect; else as it is. */
+const NEEDS_KIND = { approval: "yes", yes: "yes", question: "question", limit: "spend", connect: "connect" };
+
+/**
+ * What waits on this member in this app, as a needs-you item, or null.
+ * Pure, so the tests hold it to each case: only the member's own
+ * requests (`mine`), with a need that blocks (a `note` never does). A
+ * claw whose requests carry no `needs` still says `needs_you`: the item
+ * is then a question, in the request's own line.
+ *
+ * An item also says how the app can settle it (0.8.1, D18/D19): `via` is
+ * "answer" (a question: answer it in place with its `options` and, when
+ * `free`, the member's own words), "press" (the one ask's yes: the
+ * `approval` block's press frame) or null (on the desk: connect, spend,
+ * a tool approval, several questions at once). `needsAt` is the version
+ * of the need an answer names.
+ */
+export function needsYouItem(request) {
+  if (!request || typeof request !== "object" || !request.mine || ended(request)) return null;
+  const needs = request.needs && typeof request.needs === "object" ? request.needs : null;
+  if (needs && needs.kind === "note") return null;
+  if (!needs && request.status !== "needs_you") return null;
+  const line = typeof request.line === "string" ? request.line.replace(/^Needs you\s*·\s*/, "") : "";
+  return {
+    id: request.id,
+    request,
+    kind: needs ? (NEEDS_KIND[needs.kind] ?? needs.kind ?? "question") : "question",
+    text: (needs?.text || line || request.title || "").trim(),
+    title: request.title ?? "",
+    at: request.updated_at ?? request.created_at ?? null,
+    via: needs?.in_app === "answer" || needs?.in_app === "press" ? needs.in_app : null,
+    options: needs?.in_app === "answer" && Array.isArray(needs.options) ? needs.options : null,
+    free: needs?.free !== false,
+    needsAt: typeof needs?.at === "string" ? needs.at : null,
+  };
+}
+
+/**
+ * What waits on this member here, for the `needs-you` block (GET
+ * _claw/requests, the member's own only):
+ *
+ *   const { items, working, open, takeBack, stop } = useNeedsYou();
+ *
+ *   items     [{ id, request, kind: question | yes | spend | connect | …,
+ *              text, title, at, via: "answer" | "press" | null, options,
+ *              free, needsAt }]: the agent's questions and yeses, newest
+ *              first. A question with via "answer" is answered in place
+ *              (answer(item, …)); a yes with via "press" is the `approval`
+ *              block's press frame; anything else, open(item) takes to
+ *              the desk
+ *   working   the member's own requests the agent is working on now
+ *   open(item)       the request's conversation on the desk
+ *   answer(item, { optionId, text })   answer a question in place (0.8.1):
+ *                    → { ok } | { ok: false, error, code }; the page's
+ *                    other readers look again at once
+ *   takeBack(item)   stop the ask that waits (the frozen "Ready to send")
+ *   stop(request)    stop a working one ("Stop keeps everything written
+ *                    so far")
+ *   loading, error, code, unavailable, reload
+ *
+ * Looks every `every` ms (8 s) while the page is shown, and at once after
+ * an ask from this page.
+ */
+export function useNeedsYou({ every = 8000 } = {}) {
+  const often = Math.max(Number(every) || 8000, 1000);
+  const watched = useWatched((signal) => readRequests({ signal }), "needs-you", { next: () => often, listen: onAsked });
+  const { data, reload } = watched;
+  const list = listOf(data?.requests);
+  const items = useMemo(
+    () =>
+      list
+        .map(needsYouItem)
+        .filter(Boolean)
+        .sort((a, b) => String(b.at ?? "").localeCompare(String(a.at ?? ""))),
+    [list],
+  );
+  const working = useMemo(() => list.filter((q) => q?.mine && LIVE.has(q.status) && q.status !== "needs_you" && !needsYouItem(q)), [list]);
+  useEffect(() => {
+    if (data?.desk_origin) publishDesk(data.desk_origin);
+  }, [data]);
+
+  const open = useCallback((item) => openRequest(item?.request ?? item), []);
+  const stopOne = useCallback(
+    async (request) => {
+      const id = request?.id;
+      if (!id) return { ok: false, error: "nothing to stop" };
+      const r = await stopRequest(id);
+      reload();
+      return r;
+    },
+    [reload],
+  );
+  const takeBack = useCallback((item) => stopOne(item?.request ?? item), [stopOne]);
+  const answerOne = useCallback(
+    async (item, { optionId, text } = {}) => {
+      const id = item?.request?.id ?? item?.id;
+      if (!id) return { ok: false, error: "nothing to answer" };
+      const r = await sendAnswer(id, { optionId, text, at: item?.needsAt ?? undefined });
+      if (r.ok) announceAsk();
+      reload();
+      return r.ok ? { ok: true } : { ok: false, error: r.error, code: r.code ?? null };
+    },
+    [reload],
+  );
+
+  return {
+    items,
+    working,
+    loading: watched.loading,
+    error: watched.error,
+    code: watched.code,
+    unavailable: watched.unavailable,
+    reload,
+    open,
+    answer: answerOne,
+    takeBack,
+    stop: stopOne,
+  };
+}
+
+/** How long the press frame has to say it is ready before the card
+ *  falls back to the desk's (a frame that cannot load says nothing). */
+const FRAME_READY_MS = 7000;
+/** The frame's height, as it asks for it: kept between these. */
+const FRAME_MIN = 96;
+const FRAME_MAX = 520;
+/** What a card shows for a request whose yes is no longer there. */
+const APPROVAL_GONE = new Set(["nothing_to_approve", "unknown_request", "not_one_yes", "not_your_request"]);
+const NO_PRESS = { for: null, state: null, height: null, always: false, ready: false };
+
+/**
+ * The yes, given in the app (0.8.1, D18): the facts of one request's yes
+ * and the Makersclaw-held press frame to embed in the app's own card, for
+ * the `approval` block.
+ *
+ *   const approval = useApproval(item.id);          // item from useNeedsYou
+ *   <Approval approval={approval} title="Send 3 follow-ups"> …the draft… </Approval>
+ *
+ * The app draws the card in its theme; the press is a page of
+ * Makersclaw's in another origin, which shows the SERVER's words (the
+ * agent's question, who, from which account, the first message, the rule
+ * "Always allow this kind" would save) and only counts a press a person
+ * made on a card they can see. App code cannot press it, and this hook
+ * only listens to it.
+ *
+ *   approval   { request_id, question, label, covers, always, cap_credits,
+ *              at, frame: { src, origin }, expires_at } or null
+ *   state      idle (no request) · loading · ready (the frame is up) ·
+ *              approved · declined · stale (the question moved on; looks
+ *              again by itself) · gone (nothing waits any more: answered
+ *              elsewhere) · signin (the frame needs the member signed in
+ *              on the desk) · blocked (the frame did not load in time) ·
+ *              unavailable (a claw from before this door) · error
+ *   always     true once "Always allow this kind" was saved with the yes
+ *   fallback   true when the frame cannot be used (signin, blocked,
+ *              unavailable, error): draw WaitingYes and open the desk
+ *   frame      { src, ref, title } to spread on the <iframe>
+ *   height     the px the frame asked for, kept between 96 and 520
+ *   loading, error, code, unavailable, reload
+ *
+ * Nothing here approves. A request with no id asks nothing.
+ */
+export function useApproval(requestId, { fallbackMs = FRAME_READY_MS } = {}) {
+  const id = requestId ? String(requestId) : null;
+  const watched = useWatched((signal) => readApproval(id, { signal }), JSON.stringify(["approval", id]), {
+    enabled: Boolean(id),
+    next: () => 0,
+  });
+  const { data, reload } = watched;
+  const approval = data?.approval ?? null;
+  const src = approval?.frame?.src ?? null;
+  const origin = approval?.frame?.origin ?? null;
+  const frameRef = useRef(null);
+  const [heard, setHeard] = useState(NO_PRESS);
+  const [timedOut, setTimedOut] = useState(null);
+  const mine = heard.for === src ? heard : NO_PRESS;
+
+  useEffect(() => {
+    if (!src || !origin || typeof window === "undefined" || typeof window.addEventListener !== "function") return undefined;
+    const onMessage = (event) => {
+      const m = pressMessage(event, { origin, source: frameRef.current?.contentWindow, request: id });
+      if (!m) return;
+      if (m.state === "ready") setHeard((h) => ({ ...(h.for === src ? h : NO_PRESS), for: src, ready: true }));
+      else if (m.state === "size") {
+        const px = Math.round(Number(m.height));
+        if (Number.isFinite(px) && px > 0) setHeard((h) => ({ ...(h.for === src ? h : NO_PRESS), for: src, height: Math.min(Math.max(px, FRAME_MIN), FRAME_MAX) }));
+      } else if (m.state === "approved" || m.state === "declined") {
+        setHeard((h) => ({ ...(h.for === src ? h : NO_PRESS), for: src, state: m.state, always: m.state === "approved" && m.always === true }));
+        announceAsk();
+      } else if (m.state === "stale") {
+        // The question moved on since this card was drawn: a new ticket, or the news that nothing waits.
+        setHeard((h) => ({ ...(h.for === src ? h : NO_PRESS), for: src, state: "stale" }));
+        reload();
+      } else if (m.state === "signin") setHeard((h) => ({ ...(h.for === src ? h : NO_PRESS), for: src, state: "signin" }));
+    };
+    window.addEventListener("message", onMessage);
+    const timer = setTimeout(() => setTimedOut(src), Math.max(Number(fallbackMs) || FRAME_READY_MS, 1000));
+    return () => {
+      window.removeEventListener?.("message", onMessage);
+      clearTimeout(timer);
+    };
+  }, [src, origin, id, fallbackMs, reload]);
+
+  let state;
+  if (!id) state = "idle";
+  else if (watched.unavailable) state = "unavailable";
+  else if (watched.error) state = APPROVAL_GONE.has(watched.code) ? "gone" : "error";
+  else if (!approval) state = "loading";
+  else if (mine.state) state = mine.state;
+  else if (mine.ready) state = "ready";
+  else state = timedOut === src ? "blocked" : "ready";
+  const fallback = state === "signin" || state === "blocked" || state === "unavailable" || state === "error";
+
+  return {
+    approval,
+    state,
+    always: mine.always,
+    fallback,
+    frame: approval && src ? { src, ref: frameRef, title: "Approve" } : null,
+    height: mine.height,
+    loading: watched.loading,
+    error: watched.error,
+    code: watched.code,
+    unavailable: watched.unavailable,
+    reload,
+  };
+}
+
+/** A time as the key of a read: to the minute, so a `since` made fresh
+ *  each render (new Date(Date.now() - …)) does not read again each
+ *  render. */
+function minuteOf(time) {
+  if (time instanceof Date) return Number.isNaN(time.getTime()) ? null : time.toISOString().slice(0, 16);
+  return typeof time === "string" && time ? time.slice(0, 16) : null;
+}
+
+/**
+ * Who did what in this app, newest first, for the `activity-log` and
+ * `agent-changes` blocks (GET _claw/data/activity):
+ *
+ *   const { rows } = useActivity({ row: deal.id });   // one record's timeline
+ *   const { rows } = useActivity({ agent: true, since: askedAt });   // what the agent did
+ *
+ *   rows   [{ id, at, action, surface, row_ref, detail, data, by }]; `by`
+ *          is user:<email>, agent:<email> (on a member's ask) or agent:job
+ *   loading, error, code, unavailable, reload
+ *
+ * `row` narrows to one record's lines, `surface` to one surface, `since`
+ * (ISO or a Date, compared to the minute) to lines after it, `limit` (50);
+ * `agent: true` keeps the agent's lines only. Looks every `every` ms (20
+ * s) while the page is shown. lib/door.js's useActivity is the same lines
+ * read once, with no `row` and no polling; this one is the kit's.
+ */
+export function useActivity({ row, surface, since, limit = 50, agent = false, every = 20000 } = {}) {
+  const sinceRef = useRef(since);
+  sinceRef.current = since;
+  const key = JSON.stringify(["activity", row ?? null, surface ?? null, minuteOf(since), limit ?? null]);
+  const watched = useWatched((signal) => readActivity({ row, surface, since: sinceRef.current, limit, signal }), key, {
+    next: () => every,
+  });
+  const { data, ...rest } = watched;
+  const all = listOf(data?.rows);
+  const rows = useMemo(() => (agent ? all.filter((r) => typeof r?.by === "string" && r.by.startsWith("agent:")) : all), [all, agent]);
+  return { rows, ...rest };
+}
+
+/**
+ * Connect one of the app's declared accounts, the way the member's press
+ * should go: inside the desk, ask it to open its connections panel for
+ * that need (every provider of the kind shows; no agent turn); on the
+ * app's own host, fetch the link (POST _claw/connect) and open it in a new
+ * tab. Signing in stays the member's, at the provider.
+ *
+ * The tab is opened before the link is fetched, on the press itself, and
+ * pointed at the link once it comes: a tab opened after an await is a
+ * popup the browser blocks. → { opened: "desk" | "tab" | false,
+ * connected?, error?, code? }. Never throws. useConnections calls it.
+ */
+export async function connectAccount(key, win = typeof window === "undefined" ? undefined : window) {
+  if (openConnections(key, win)) return { opened: "desk" };
+  let tab = null;
+  try {
+    tab = win?.open?.("about:blank", "_blank") ?? null;
+    if (tab) tab.opener = null;
+  } catch {
+    tab = null;
+  }
+  const r = await connectLink(key);
+  const url = r.ok && typeof r.data?.url === "string" && /^https?:\/\//i.test(r.data.url) ? r.data.url : null;
+  if (!url) {
+    try {
+      tab?.close?.();
+    } catch {
+      /* a tab the browser already took back */
+    }
+    if (r.ok && r.data?.connected) return { opened: false, connected: true };
+    if (r.ok) return { opened: false, error: "no link came back" };
+    return { opened: false, error: r.unavailable ? null : r.error, code: r.code ?? null, unavailable: Boolean(r.unavailable) };
+  }
+  try {
+    if (tab) {
+      tab.location.href = url;
+      return { opened: "tab" };
+    }
+    const opened = win?.open?.(url, "_blank", "noopener");
+    return { opened: opened === undefined ? false : "tab" };
+  } catch {
+    return { opened: false, error: "the browser would not open the link" };
+  }
+}
+
+/** Is a real account behind this connection? `connected` is the
+ *  workspace listing the toolkit, which can be true while the list of
+ *  accounts that meet it is empty: a toolkit that needs no sign-in, or a
+ *  leftover (an account removed at the provider). A screen that needs an
+ *  account (a mailbox to read, a calendar to sync) asks this, not
+ *  `connected`, before it says "Connected" or offers the read: the CRM's
+ *  "Connect your mailbox" card said "Connected" over nothing (2026-10-11).
+ *  False without an `accounts` list (a claw from before it) only when
+ *  `connected` is false too. */
+export function hasAccount(c) {
+  if (!c || !c.connected) return false;
+  return Array.isArray(c.accounts) ? c.accounts.filter(Boolean).length > 0 : true;
+}
+
+/**
+ * The app's declared accounts, for the `connect-card` block (GET
+ * _claw/connect):
+ *
+ *   const { connections, connect } = useConnections();
+ *   <ConnectCard connections={connections} onConnect={connect} />
+ *
+ *   connections  [{ key, label, toolkits, required, connected, accounts,
+ *                 category, category_label }]
+ *   connecting   the key being connected while it is watched, or null
+ *   connect(key) → { opened: "desk" | "tab" | false, error? }
+ *                (connectAccount), then looks every 3 s for two minutes
+ *                until that account is connected
+ *   loading, error, code, unavailable, reload
+ *
+ * Read once, then only while an account is being connected (or every
+ * `every` ms when given), and at once when the page comes back.
+ */
+export function useConnections({ every } = {}) {
+  const watchRef = useRef(null); // { key, until }
+  const [connecting, setConnecting] = useState(null);
+  const watched = useWatched((signal) => readConnections({ signal }), "connections", {
+    next: (data) => {
+      const watch = watchRef.current;
+      if (watch) {
+        const met = listOf(data?.connections).some((c) => c?.key === watch.key && c.connected);
+        if (met || Date.now() > watch.until) {
+          watchRef.current = null;
+          setConnecting(null);
+        } else return CONNECTING_MS;
+      }
+      return every ?? 0;
+    },
+  });
+  const { data, reload } = watched;
+
+  const connect = useCallback(
+    async (key) => {
+      const r = await connectAccount(key);
+      if (r.opened) {
+        watchRef.current = { key, until: Date.now() + CONNECTING_FOR_MS };
+        setConnecting(key);
+      }
+      reload();
+      return r;
+    },
+    [reload],
+  );
+
+  return {
+    connections: listOf(data?.connections),
+    connecting,
+    loading: watched.loading,
+    error: watched.error,
+    code: watched.code,
+    unavailable: watched.unavailable,
+    reload,
+    connect,
+  };
+}
+
+/** What the agent knows and can do, from GET _claw/agent's answer. Pure:
+ *  the app's own skills first (from: "app"), then those added on top
+ *  (from: "added", installed or not), then its tools — the declared
+ *  actions the agent may run. */
+export function agentKitOf(data) {
+  const own = listOf(data?.own_skills)
+    .filter((s) => s && typeof s.name === "string")
+    .map((s) => ({ name: s.name, title: s.title || s.name, when: s.when ?? null, from: "app", installed: true }));
+  const ownNames = new Set(own.map((s) => s.name));
+  const added = listOf(data?.skills)
+    .filter((s) => s && typeof s.name === "string" && !ownNames.has(s.name))
+    .map((s) => ({ name: s.name, title: s.title || s.name, when: s.when ?? null, from: "added", installed: Boolean(s.installed) }));
+  const tools = listOf(data?.actions)
+    .filter((a) => a && typeof a.name === "string" && a.agent !== false)
+    .map((a) => ({ name: a.name, description: a.description ?? "" }));
+  return { skills: [...own, ...added], tools };
+}
+
+/**
+ * What the app's agent knows and can do, for the `agent-kit` block (GET
+ * _claw/agent): `skills` [{ name, title, when, from: "app" | "added",
+ * installed }] and `tools` [{ name, description }] (agentKitOf), with
+ * loading, error, code, unavailable, reload. Read once.
+ */
+export function useAgentKit() {
+  const watched = useWatched((signal) => readAgentKit({ signal }), "agent-kit");
+  const { data, ...rest } = watched;
+  const kit = useMemo(() => agentKitOf(data), [data]);
+  return { ...kit, ...rest };
+}
+
+/** How long useLlmAction waits for the input to settle before it asks
+ *  for a price. */
+const ESTIMATE_AFTER_MS = 400;
+
+/**
+ * One model call on what the screen holds, with its price before the
+ * press, for the `ai-action` and `cost` blocks:
+ *
+ *   const shorter = useLlmAction({ input: text, system: "Make it shorter.", task: "shorten" });
+ *   <AiAction label="Shorter" action={shorter} onUse={(r) => setText(r.text)} />
+ *
+ *   estimate    { credits, credits_max } or null: the price, asked of the
+ *               platform (llmEstimate: priced, never sent to a model,
+ *               never charged) once per distinct input, 400 ms after it
+ *               settles. Null for an empty input, and on a claw with no
+ *               estimate yet. While a new input is priced the last price
+ *               stays, with `estimating` true
+ *   estimating  a price is being asked for
+ *   run()       the call, with the same arguments → llm()'s answer
+ *   result, loading, error, unavailable   as useLlm
+ *   reset()     back to nothing shown
+ *
+ * Options: llm()'s — input, system, schema, tier, task, maxTokens — and
+ * `estimate` (default true; false asks no price).
+ */
+export function useLlmAction({ input, system, schema, tier, task, maxTokens, estimate = true } = {}) {
+  const call = useLlm();
+  const argsRef = useRef(null);
+  argsRef.current = { input, opts: { system, schema, tier, task, maxTokens } };
+  const priced = Boolean(estimate) && saidSomething(input);
+  let key = null;
+  if (priced) {
+    try {
+      key = JSON.stringify([input, system ?? null, schema ?? null, tier ?? null, task ?? null, maxTokens ?? null]);
+    } catch {
+      key = null; // an input that is not JSON: llm() refuses it too
+    }
+  }
+  const cacheRef = useRef(new Map());
+  const [price, setPrice] = useState({ key: null, value: null, estimating: false });
+
+  useEffect(() => {
+    if (!key) return undefined;
+    const known = cacheRef.current.get(key);
+    if (known !== undefined) {
+      setPrice({ key, value: known, estimating: false });
+      return undefined;
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(async () => {
+      setPrice((p) => ({ ...p, estimating: true }));
+      const { input: now, opts } = argsRef.current;
+      const r = await llmEstimate(now, { ...opts, signal: controller.signal });
+      if (controller.signal.aborted || r.aborted) return;
+      const value =
+        r.ok && r.estimate && typeof r.estimate === "object" && typeof r.estimate.credits === "number"
+          ? { credits: r.estimate.credits, credits_max: typeof r.estimate.credits_max === "number" ? r.estimate.credits_max : r.estimate.credits }
+          : null;
+      if (r.ok) cacheRef.current.set(key, value);
+      setPrice({ key, value, estimating: false });
+    }, ESTIMATE_AFTER_MS);
+    return () => {
+      clearTimeout(timer);
+      controller.abort();
+    };
+  }, [key]);
+
+  const run = useCallback(() => {
+    const { input: now, opts } = argsRef.current;
+    return call.run(now, opts);
+  }, [call.run]);
+
+  return {
+    estimate: key ? price.value : null,
+    estimating: Boolean(key) && (price.estimating || (price.key !== key && !cacheRef.current.has(key))),
+    run,
+    result: call.result,
+    loading: call.loading,
+    error: call.error,
+    unavailable: call.unavailable,
+    reset: call.reset,
+  };
+}
+
+// The automations engine's hooks (useAutomations, useAutomation,
+// useAutomationRun) live in lib/automations.js, with their doors; a surface
+// imports them from here with the others.
+export * from "./automations";