makersclaw 0.7.0 → 0.8.1

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

@@ -18,9 +18,25 @@
 // lib/platform.js wraps them as ask / requests / stopRequest and
 // lib/hooks.js as useJob and useRequests. `chat` and `cancel` are the
 // 0.3.x door to the same work, streamed into the app (startJob /
-// cancelJob): kept for a claw that has no `ask` yet. What an app still
-// never calls is monitoring: the OS draws Agent, Runs and Activity as
-// tabs on its window. The rest of the gateway's routes (§5) stay
+// cancelJob): kept for a claw that has no `ask` yet. `llm` (0.8.0) is one
+// shot of model work answered in the page, not asking an agent: lib/
+// platform.js wraps it as llm and lib/hooks.js as useLlm, and the check
+// refuses a screen that names its path. `library` (0.8.1) is the
+// Library's door, read only: collections of files and rows that Makersclaw
+// keeps; lib/platform.js wraps it as library, lib/hooks.js as the
+// useLibrary… hooks, and the check refuses a screen that names its path
+// too. `threads` (0.8.1) reads the member's own threads in this app, the
+// same conversation the desk's column shows: lib/platform.js wraps it as
+// threads / thread, lib/hooks.js as useAgentThread, and the `agent-chat`
+// block draws it — the app's own chat. Since the kit (0.8.1, D15) the
+// app also reads its own jobs, runs, activity, accounts and agent kit
+// (`jobs`, `runs`, `data/activity`, `connect`, `agent`) and may press Run
+// now, the on/off switch and Live (`run`, `jobs/:id`, `pause`, `resume`):
+// lib/platform.js wraps them, lib/hooks.js follows them, and the kit's
+// blocks draw them in the app's look. The OS kept them as tabs so every
+// app looked the same; the blocks now give that sameness inside the app,
+// and the tabs stay as the full history. The yes, the account sign-in
+// and money stay on the desk. The rest of the gateway's routes (§5) stay
 // reachable through claw() / clawStream() for a surface that has a real
 // reason.
 
@@ -127,13 +143,24 @@ function framed(win) {
  * Ask the desk to open a request's conversation in its agent column.
  * Posts only when the app is framed and the desk's origin is known, and
  * only to that origin. → true when the message went.
+ *
+ * `show` (0.8.1): the member pressed something to see it on the desk
+ * ("Open on the desk", a yes's link). An app that draws its own chat (the
+ * `agent-chat` block, `"agent_in_app": true` in the package's blueprint)
+ * has its column opened only then; without it the desk only points its
+ * column at the conversation, quietly.
  */
-export function openInDesk({ requestId, sessionId } = {}, win = currentWindow()) {
+export function openInDesk({ requestId, sessionId, show = false } = {}, win = currentWindow()) {
   const origin = deskOrigin();
   if (!requestId || !origin || !framed(win)) return false;
   try {
     win.parent.postMessage(
-      { type: OPEN_REQUEST_MESSAGE, request_id: String(requestId), session_id: sessionId ? String(sessionId) : null },
+      {
+        type: OPEN_REQUEST_MESSAGE,
+        request_id: String(requestId),
+        session_id: sessionId ? String(sessionId) : null,
+        ...(show ? { show: true } : {}),
+      },
       origin,
     );
     return true;
@@ -142,12 +169,121 @@ export function openInDesk({ requestId, sessionId } = {}, win = currentWindow())
   }
 }
 
+/** The message the app posts to the desk: open the connections panel
+ *  for one of the app's declared accounts (0.8.1, the kit's
+ *  `connect-card`). The desk checks the key against the app's declared
+ *  needs and opens its drawer for that need's category, so every
+ *  provider of the kind shows; signing in stays the member's, at the
+ *  provider. */
+export const OPEN_CONNECTIONS_MESSAGE = "claw:open-connections";
+
+/** A declared account's key, as the desk takes it. */
+const CONNECTION_KEY = /^[a-z0-9_-]{1,64}$/i;
+
+/**
+ * Ask the desk to open its connections panel for the declared account
+ * `key`. Posts only when the app is framed, the desk's origin is known
+ * and the key has the desk's shape, and only to that origin, like
+ * openInDesk. → true when the message went; false means there is no desk
+ * to ask (the app on its own host): hand out the link instead
+ * (lib/platform.js connectLink).
+ */
+export function openConnections(key, win = currentWindow()) {
+  const origin = deskOrigin();
+  if (typeof key !== "string" || !CONNECTION_KEY.test(key) || !origin || !framed(win)) return false;
+  try {
+    win.parent.postMessage({ type: OPEN_CONNECTIONS_MESSAGE, key }, origin);
+    return true;
+  } catch {
+    return false; // a parent that will not take messages
+  }
+}
+
+/** The messages the app posts to the desk: open an app the agent made, or
+ *  a file it wrote (0.8.1, D27 phase 4: the `agent-pane` block's "Open").
+ *  The desk checks the sender is this frame and the ids have their shape
+ *  (claw's web/src/components/play/frame-grant.ts), then navigates; the app
+ *  never navigates the desk itself. */
+export const OPEN_APP_MESSAGE = "claw:open-app";
+export const OPEN_FILE_MESSAGE = "claw:open-file";
+
+/** An app's id as the desk takes it: a uuid. */
+const APP_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Ask the desk to open an app the agent made. Posts only when the app is
+ * framed, the desk's origin is known and the id is a uuid, and only to that
+ * origin, like openInDesk. → true when the message went; false means there
+ * is no desk to ask (the app on its own host).
+ */
+export function openApp(id, win = currentWindow()) {
+  const origin = deskOrigin();
+  if (typeof id !== "string" || !APP_ID.test(id) || !origin || !framed(win)) return false;
+  try {
+    win.parent.postMessage({ type: OPEN_APP_MESSAGE, id }, origin);
+    return true;
+  } catch {
+    return false; // a parent that will not take messages
+  }
+}
+
+/**
+ * Ask the desk to open a file the agent wrote: `where` is "workspace" (the
+ * workspace's Files, at `path`) or "app" (the app `appRef`). Same rules as
+ * openApp. → true when the message went.
+ */
+export function openFile({ path, where, appRef } = {}, win = currentWindow()) {
+  const origin = deskOrigin();
+  if (!origin || !framed(win)) return false;
+  if (where === "workspace") {
+    if (typeof path !== "string" || !path || path.length > 500) return false;
+  } else if (where === "app") {
+    if (typeof appRef !== "string" || !APP_ID.test(appRef)) return false;
+  } else {
+    return false;
+  }
+  try {
+    win.parent.postMessage(
+      { type: OPEN_FILE_MESSAGE, where, ...(where === "workspace" ? { path } : { app_ref: appRef }) },
+      origin,
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /** Is this message from the desk, of this type? Only the window around
  *  the frame may send one — app/frame.js isDeskEscape, for any type. */
 export function isDeskMessage(event, type, win = currentWindow()) {
   return Boolean(framed(win) && event?.source === win.parent && event?.data?.type === type);
 }
 
+/** The message the press frame posts to the page that embeds it (0.8.1,
+ *  D18; the `approval` block, useApproval): `ready`, `size`, `approved`,
+ *  `declined`, `stale`, `signin`, `error`. The frame is a page of
+ *  Makersclaw's in another origin, so the only thing this page can do with
+ *  it is listen. */
+export const PRESS_MESSAGE = "claw:press";
+
+/**
+ * Read a message as the press frame's, or null. Only what came from the
+ * frame's own window AND its own origin counts, and only for the request
+ * it was drawn for: app code in another frame, or a script posting to
+ * itself, cannot make the page believe a yes was given. (It could not
+ * give one anyway: the press is the frame's and the server's. This only
+ * keeps the card's words true.)
+ *   → { type, request_id, state, … } | null
+ */
+export function pressMessage(event, { origin, source, request } = {}) {
+  if (!event || typeof origin !== "string" || !origin || event.origin !== origin) return null;
+  if (!source || event.source !== source) return null;
+  const data = event.data;
+  if (!data || typeof data !== "object" || data.type !== PRESS_MESSAGE) return null;
+  if (request && data.request_id !== request) return null;
+  return data;
+}
+
 /** A refusal's words, and its `code` when the gateway names one
  *  (`not_your_thread`, `needs_answer`, …): the code is what a caller
  *  branches on, the words are what it shows. */
@@ -299,19 +435,122 @@ export async function clawStream(path, body, onEvent, { signal } = {}) {
   return { ok: true, status: res.status, data: null };
 }
 
+/**
+ * GET a newline-delimited JSON stream (0.8.1, D27 phase 4: the thread
+ * pushed as the agent writes). `onLine(object)` is called for every line as
+ * it arrives. Resolves when the stream ends, with claw()'s shape: a 404
+ * (`unavailable`, or with a `code` a route refusing) or another refusal
+ * comes back as itself; a clean end is { ok: true }; a broken body is
+ * { ok: false, error } so the caller falls back to polling.
+ */
+export async function clawNdjson(path, onLine, { signal } = {}) {
+  let res;
+  try {
+    res = await fetch(clawUrl(path), {
+      method: "GET",
+      credentials: "same-origin",
+      cache: "no-store",
+      headers: { accept: "application/x-ndjson" },
+      signal,
+    });
+  } catch (error) {
+    if (error?.name === "AbortError") return { ok: false, status: 0, error: "aborted", aborted: true };
+    return { ok: false, status: 0, error: "not reachable", unavailable: true };
+  }
+  if (res.status === 404) return notFound(res);
+  if (!res.ok) return { ok: false, status: res.status, ...(await readFailure(res)), unavailable: false };
+  if (!res.body) return { ok: false, status: res.status, error: "empty stream" };
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  const dispatch = (line) => {
+    const text = line.trim();
+    if (!text) return;
+    let parsed = null;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      return; // a torn line is skipped
+    }
+    if (parsed && typeof parsed === "object") onLine(parsed);
+  };
+  try {
+    for (;;) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      let idx;
+      while ((idx = buffer.indexOf("\n")) >= 0) {
+        dispatch(buffer.slice(0, idx));
+        buffer = buffer.slice(idx + 1);
+      }
+    }
+    dispatch(buffer);
+  } catch (error) {
+    if (error?.name === "AbortError") return { ok: false, status: 0, error: "aborted", aborted: true };
+    return { ok: false, status: res.status, error: `stream broke: ${String(error)}` };
+  }
+  return { ok: true, status: res.status, data: null };
+}
+
 let posted = 0;
 const seen = new Set();
 
+/**
+ * Browser notices that are not errors (0.8.1, D28). A browser tells a page
+ * some things through window.onerror that nothing in the app caused and
+ * nobody can act on. The worst is "ResizeObserver loop completed with
+ * undelivered notifications": a resize callback ran out of frames and the
+ * rest waits for the next one. Reported as an error it used to start a
+ * repair of the app, which found nothing to change. They are never sent.
+ *
+ * Kept in step with claw's agent-app/src/lib/app-error-notices.ts, which
+ * drops the same ones again at the _claw/events door (an app on an older
+ * template still reports them). A notice joins the list only with a reason
+ * and a test (test/error-report.test.mjs). When unsure, report.
+ */
+export const HARMLESS_NOTICES = [
+  {
+    name: "resize-observer",
+    message: /^ResizeObserver loop (completed with undelivered notifications|limit exceeded)\.?$/i,
+  },
+  { name: "script-error", message: /^Script error\.?$/i },
+  {
+    name: "aborted-request",
+    message:
+      /^(AbortError: )?(The (user|operation) aborted( a request| was aborted)?|signal is aborted without reason|The operation was aborted|Fetch is aborted|The user aborted a request)\.?$/i,
+  },
+  { name: "browser-extension", stack: /(chrome|moz|safari|ms-browser)-extension:\/\//i },
+];
+
+/** The name of the harmless notice this is, or null for a real error. */
+export function harmlessNotice(message, stack) {
+  const text = typeof message === "string" ? message.trim() : "";
+  const trace = typeof stack === "string" ? stack : "";
+  for (const notice of HARMLESS_NOTICES) {
+    if (notice.message?.test(text)) return notice.name;
+    if (notice.stack && (notice.stack.test(trace) || notice.stack.test(text))) return notice.name;
+  }
+  return null;
+}
+
 /**
  * Report a browser-side error to Makersclaw (POST _claw/events). Deduped
  * by message+stack and capped per page load, so an error that fires on
  * every render cannot flood the gateway. Best-effort: never throws.
+ * A harmless browser notice (harmlessNotice, above) is not reported.
+ * Nothing is repaired because of a report: it lands on the app's error
+ * list in the Activity tab and the member presses Fix it (D28).
  *
  * `source` defaults to errorSource() — "preview" while the artifact is a
  * draft, "runtime" once launched — so the bench and the platform agent can
  * tell the two apart. Pass it only when the caller knows better.
  */
 export async function reportError({ message, stack, url, source }) {
+  // A browser notice is not an error: not sent, and not counted against
+  // the page's 20.
+  const notice = harmlessNotice(message, stack);
+  if (notice) return { ok: false, status: 0, error: "ignored", ignored: notice };
   const key = `${message}\n${stack ?? ""}`;
   if (seen.has(key) || posted >= 20) return { ok: false, status: 0, error: "skipped" };
   seen.add(key);

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

@@ -35,6 +35,10 @@ import { surfaceOfPath } from "./platform";
 //   - Every write that answers ok calls dataChanged(). Every mounted hook
 //     reads again, and whenLanded() resolves once they have all handed
 //     out their new rows, in one pass.
+//   - A page that opens a row it just made does it with afterWrite(): the
+//     write, then the hooks' new rows, then the open. A record page says
+//     "not found" only through useNotFound(): never while a write or a
+//     re-read is out, which is when the new row is not in the page yet.
 //   - Nothing here logs activity: the door writes the line. `data` on
 //     updateRow is taken and never sent (a value never goes in a line).
 
@@ -253,15 +257,25 @@ export function loadActivity(args) {
 // Actions so; plain fetches overlap, and a whole-document save that
 // answered slowly would land over the newer one after it.
 let turn = Promise.resolve();
+let writesOut = 0;
 
 /** Run `work` once every write called before it has answered. The
  *  brain's writes (lib/brain.js) take their turn here too. */
 export function inTurn(work) {
+  writesOut += 1;
+  announce();
   const run = turn.then(work, work);
   turn = run.then(
     () => undefined,
     () => undefined,
   );
+  // `work` has called dataChanged() by the time it answers, so the page is
+  // never "settled" between a write answering and its re-read starting.
+  const done = () => {
+    writesOut -= 1;
+    announce();
+  };
+  run.then(done, done);
   return run;
 }
 
@@ -438,6 +452,7 @@ export function dataChanged() {
     return;
   }
   startLanding();
+  announce();
 }
 
 /** Resolves when every read the last dataChanged() started has answered
@@ -447,6 +462,81 @@ export function whenLanded() {
   return new Promise((resolve) => waiting.push(resolve));
 }
 
+/** A write, and then the page holding what it wrote: resolves with the
+ *  write's own answer once the hooks have handed out their new rows. A
+ *  failed write (`ok: false`) answers at once, with nothing to wait for.
+ *  This is the way to do "make a row, then open it":
+ *
+ *    const out = await afterWrite(runAction({ name: "add_project", args }));
+ *    if (out.ok) router.push(`/s/today?row=${out.result.id}`);
+ *
+ *  Without it the page opens a row the hooks do not hold yet. Takes a
+ *  promise or an answer already in hand. Never throws. */
+export async function afterWrite(write) {
+  let out;
+  try {
+    out = await write;
+  } catch (error) {
+    return { ok: false, error: String(error?.message ?? error), code: "failed" };
+  }
+  if (out && out.ok === false) return out;
+  await whenLanded();
+  return out;
+}
+
+// Whether the page holds what was written. Settled: no write is out, no
+// re-read is out, none is waiting to start. A record page asks this before
+// it says "not found" (useNotFound), so it never says it against a world
+// that was read before the last write.
+const watchers = new Set();
+const isSettled = () => writesOut === 0 && !landing && !again;
+
+function announce() {
+  const now = isSettled();
+  for (const watch of [...watchers]) {
+    try {
+      watch(now);
+    } catch {
+      /* one watcher's failure is not the others' */
+    }
+  }
+}
+
+/** True while the page holds everything written so far: no write is out,
+ *  and the re-read after the last one has landed. False the moment a write
+ *  is called until its rows are in the hooks. */
+export function useSettled() {
+  const [settled, set] = useState(isSettled);
+  useEffect(() => {
+    watchers.add(set);
+    set(isSettled());
+    return () => {
+      watchers.delete(set);
+    };
+  }, []);
+  return settled;
+}
+
+/**
+ * Whether a record page may say "not found" now. A record page looks its
+ * row up in what the hooks hold; right after a create that is the world
+ * read BEFORE the write, and the row is not in it yet. So "not found" is
+ * only ever said about a read that started after the last write:
+ *
+ *   const gone = useNotFound(Boolean(project), { loading: world.loading });
+ *   if (!project) return gone ? <NotFound /> : <Loading />;
+ *
+ *   found    whether the record is in what the page holds
+ *   loading  whether the page's first read is still out (default false)
+ *   → true only when it is not found, nothing is loading, and no write or
+ *   re-read is out. While it is false and `found` is false, show the
+ *   loading state.
+ */
+export function useNotFound(found, { loading = false } = {}) {
+  const settled = useSettled();
+  return !found && !loading && settled;
+}
+
 function startLanding() {
   again = false;
   const run = { open: true, pending: new Set(), handOut: [], timer: null };
@@ -493,9 +583,11 @@ function closeLanding(run) {
   if (landing === run) landing = null;
   if (again) {
     startLanding();
+    announce();
     return;
   }
   for (const resolve of waiting.splice(0)) resolve();
+  announce();
 }
 
 // A hook's options are compared by value on every render: a new object