makersclaw 0.3.2 → 0.4.0

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

@@ -1,29 +1,126 @@
-import { claw, clawStream, reportError } from "./claw";
+import { claw, clawBasePath, clawStream, openInDesk, publishDesk, reportError } from "./claw";
 
 // Typed wrappers over the _claw API (lib/claw.js), one per route an app
 // has a reason to call. BROWSER only — the grant cookie is the identity —
 // so call these from "use client" files; lib/hooks.js wraps them.
 //
 // Every call resolves { ok, status, data } or { ok: false, status, error,
-// unavailable }; nothing throws. `unavailable: true` (404 or no network)
-// means the gateway has no such route yet — render a quiet "not connected
-// yet" state, not an error.
+// unavailable, code? }; nothing throws. `unavailable: true` (404 or no
+// network) means the gateway has no such route yet — render a quiet "not
+// connected yet" state, not an error. `code` names a refusal a caller
+// can act on (`not_your_thread`, `needs_answer`, `queue_full`).
 //
-// Three things live here: who the app is (`me`), the error relay
-// (`reportError`), and COMMISSIONING — `startJob` / `cancelJob`, the work
-// a founder asks for from inside the app (SOP §2.3). Monitoring is still
-// not an app's business: the OS draws Agent, Runs and Activity as tabs on
-// the window and the title bar holds the run controls, so nothing here
-// lists chats, runs or activity. `claw(path, opts)` and `clawStream` in
-// lib/claw.js are the generic doors for the rest of §5.
+// What lives here: who the app is (`me`), the error relay
+// (`reportError`), and ASKING — a screen asks its agent for work with a
+// row as context (`ask`), and the conversation lives in the desk's agent
+// column, which the ask opens. `requests` reads this app's asks in
+// flight, so an empty surface can show the work coming instead of a
+// blank; `stopRequest` stops one; `openRequest` opens one in the column
+// again. That is not monitoring: the OS still draws Agent, Runs and
+// Activity as tabs on the window, and nothing here lists chats, runs or
+// activity. `startJob` / `cancelJob` are the 0.3.x door to the same work,
+// streamed into the app; they stay for a claw that has no _claw/ask yet.
+// `claw(path, opts)` and `clawStream` in lib/claw.js are the generic
+// doors for the rest of §5.
 
 /** GET _claw/me → { artifact: { id, name, vehicle, status, home },
- *  user: { id, email }, blueprint } */
+ *  user: { id, email }, blueprint, desk_origin } */
 export function me() {
   return claw("me");
 }
 
+/** The surface the page is on: the <key> of /s/<key>. Searched anywhere
+ *  in the path, not only at its start, because in path mode the app is
+ *  served under /p/<label>/ and the browser's path carries that prefix.
+ *  The base path is cut first when it is there, so a label that happens
+ *  to read "s" cannot pass for the surface. */
+export function surfaceOfPath(pathname) {
+  let path = String(pathname ?? "");
+  const base = clawBasePath();
+  if (base && path.startsWith(`${base}/`)) path = path.slice(base.length);
+  const match = /\/s\/([^/?#]+)/.exec(path);
+  if (!match) return undefined;
+  try {
+    return decodeURIComponent(match[1]);
+  } catch {
+    return match[1];
+  }
+}
+
+function currentSurface() {
+  return typeof location === "undefined" ? undefined : surfaceOfPath(location.pathname);
+}
+
 /**
+ * Ask the app's agent for work: POST _claw/ask. The platform makes it a
+ * request, hands it to the app's agent, and the conversation lives in the
+ * desk's agent column — which this opens, unless `open` is false.
+ *
+ *   text       what to do, in the founder's words (required)
+ *   row        the row it is about, as context for the agent
+ *   how        instructions for the agent only (the AGENTS.md section)
+ *   job        a declared job's key, or true: let the platform pick the
+ *              job whose view is this surface, else the app's only job
+ *   list       the list it belongs to, for an app that declares lists
+ *   surface    defaults to the <key> of /s/<key> in the page's path
+ *   sessionId  continue this thread instead of starting one
+ *
+ * → { ok: true, status, data: { ok, request, desk_origin } }, or a
+ * refusal with its `code`: `not_your_thread` (403, a teammate's thread:
+ * start your own), `needs_answer` (409, the thread waits on an answer in
+ * the column), `queue_full` (409).
+ */
+export async function ask({ text, row, how, job, list, surface, sessionId, open = true, signal } = {}) {
+  const words = String(text ?? "").trim();
+  if (!words) return { ok: false, status: 0, error: "nothing to ask", unavailable: false };
+  const r = await claw("ask", {
+    method: "POST",
+    body: {
+      text: words,
+      row: row ?? undefined,
+      how: how || undefined,
+      // true or a key; anything else is no job, and the key is left out.
+      job: job === true || (typeof job === "string" && job) ? job : undefined,
+      list: list ?? undefined,
+      surface: surface ?? currentSurface(),
+      session_id: sessionId || undefined,
+    },
+    signal,
+  });
+  if (r.ok) {
+    publishDesk(r.data?.desk_origin);
+    const request = r.data?.request;
+    if (open && request?.id) openInDesk({ requestId: request.id, sessionId: request.app_session_id });
+  }
+  return r;
+}
+
+/** GET _claw/requests → { requests, run, desk_origin }: this app's asks
+ *  in flight (and those that ended in the last day), every member's, with
+ *  session ids only on the viewer's own, plus its running scheduled run.
+ *  With { id }: GET _claw/requests?id=<id> → { request }. */
+export function requests({ id, signal } = {}) {
+  return claw(id ? `requests?id=${encodeURIComponent(id)}` : "requests", { signal });
+}
+
+/** POST _claw/requests/<id>/stop → { ok, request }. The asker may stop
+ *  their own; an admin or the app's owner may stop anyone's. */
+export function stopRequest(id) {
+  return claw(`requests/${encodeURIComponent(id)}/stop`, { method: "POST", body: {} });
+}
+
+/** Open a request's conversation in the desk's agent column again. Takes
+ *  the request (its thread opens with it when it is yours) or its id.
+ *  → true when the desk was asked. */
+export function openRequest(requestOrId) {
+  const request = requestOrId && typeof requestOrId === "object" ? requestOrId : { id: requestOrId };
+  return openInDesk({ requestId: request.id, sessionId: request.app_session_id ?? null });
+}
+
+/**
+ * Legacy: the 0.3.x job door. useJob falls back to it on a claw that has
+ * no _claw/ask; new code calls ask().
+ *
  * Commission work: POST _claw/chat as a stream, and call `onEvent` for
  * every frame — `session` (once, first, carrying the thread's id),
  * `delta` ({ text } as the answer is written), `tool` ({ name, label,
@@ -46,14 +143,15 @@ export function startJob(message, { sessionId, onEvent, signal } = {}) {
   );
 }
 
-/** POST _claw/cancel — stop a job's turn. The rows it already wrote stay;
- *  so does its run in the Runs tab. */
+/** Legacy: the 0.3.x job door (stopRequest is the new one). POST
+ *  _claw/cancel — stop a job's turn. The rows it already wrote stay; so
+ *  does its run in the Runs tab. */
 export function cancelJob(sessionId) {
   return claw("cancel", { method: "POST", body: { session_id: sessionId } });
 }
 
 export { reportError };
 
-export const platform = { me, startJob, cancelJob, reportError };
+export const platform = { me, ask, requests, stopRequest, openRequest, surfaceOfPath, startJob, cancelJob, reportError };
 
 export default platform;

package/templates/next/files/surfaces/README.md

@@ -25,6 +25,9 @@ that follows it — `useJob()` in `../lib/hooks.js`, §5 of `../README.md`.
 The panel is not a surface and takes no key: it opens because the founder
 pressed something and closes when the work lands.
 
+An empty table shows `LiveEmpty` — the live work coming, never an
+example (`../README.md` §3a).
+
 Register each in `../surfaces.js` (import + entry with `component`).
 Until the entry has a `component` the surface is planned: marked in the
 nav, "Makersclaw is building this" on its page.

package/templates/next/template.json

@@ -1,7 +1,7 @@
 {
   "name": "next",
   "title": "Makersclaw app (Next.js 15)",
-  "description": "The behaviour every app shares, the parts every app is assembled from, and none of the app's own look — the colours are the workspace's. It carries the data layer (lib/data.js, lib/db.js), the write actions that log activity (lib/actions.js), the _claw platform client with its identity wrapper and hooks (lib/claw.js, lib/platform.js, lib/hooks.js), routing (/s/<key>), the middleware, error boundaries, Tailwind v4 mapped to the workspace theme (app/globals.css + _claw/theme.css), the kit (components/ui), the parts bound to the data layer (components/parts) and `npm run check`. The app designs the inside of the App tab on top: app/shell.jsx and every domain surface, assembled from the kit and the blocks with tokens only.",
+  "description": "The behaviour every app shares, the parts every app is assembled from, and none of the app's own look — the colours are the workspace's. It carries the data layer (lib/data.js, lib/db.js), the write actions that log activity (lib/actions.js), the _claw platform client with its identity wrapper, the ask bridge (a screen's ask becomes a request, answered in the desk's agent column) and the hooks that follow requests (lib/claw.js, lib/platform.js, lib/hooks.js), routing (/s/<key>), the middleware, error boundaries, Tailwind v4 mapped to the workspace theme (app/globals.css + _claw/theme.css), the kit (components/ui), the parts bound to the data layer and to the live requests (components/parts) and `npm run check`. The app designs the inside of the App tab on top: app/shell.jsx and every domain surface, assembled from the kit and the blocks with tokens only.",
   "files": {
     "fixed": [
       "app/globals.css",
@@ -12,6 +12,9 @@
       "app/not-found.jsx",
       "app/error-relay.jsx",
       "app/auto-refresh.jsx",
+      "app/escape-relay.jsx",
+      "app/frame.js",
+      "app/claw-alive/route.js",
       "app/s/[key]/page.jsx",
       "lib/*.js",
       "components/ui/*",
@@ -30,7 +33,7 @@
       "name": "button",
       "type": "component",
       "title": "Button, IconButton",
-      "description": "The one button: variant primary (one per surface) · secondary · quiet · danger · link (inline text: no padding, no min-height, wraps and truncates with its sentence; size inherit takes the sentence's text; tone primary · muted for a secondary link) · nav (a full-width, start-aligned, normal-weight navigation row, filled when aria-current); size md (44px) · sm; align center · start; icon; href for a link; loading (a spinner, same width, aria-busy, disabled). IconButton for an icon alone, label required.",
+      "description": "The one button: variant primary (the surface's one main action, in the app's accent; ask for it — a Button with no variant is secondary) · secondary (the default) · quiet · danger · link (inline text: no padding, no min-height, wraps and truncates with its sentence; size inherit takes the sentence's text; tone primary · muted for a secondary link) · nav (a full-width, start-aligned, normal-weight navigation row, filled when aria-current); size md (44px) · sm; align center · start; icon; href for a link; loading (a spinner, same width, aria-busy, disabled). IconButton for an icon alone, label required.",
       "tags": ["button", "action", "link", "icon button"],
       "files": ["components/ui/button.jsx"]
     },
@@ -102,7 +105,7 @@
       "name": "date-picker",
       "type": "component",
       "title": "DatePicker, DateInput, DATE_PRESETS",
-      "description": "DatePicker: a field that reads like an input and opens a Calendar in a Popover — mode single · range (formatRange in the field), presets beside the calendar (true for Today, Last 7 days, This month… or your own), clearable, disabled, min/max, a hidden input for forms; goes in <Field>. DateInput: the browser's own typed date field with the Calendar one button away.",
+      "description": "DatePicker: a field that reads like an input and opens a Calendar in a Popover — mode single · range (formatRange in the field), presets beside the calendar (true for Today, Last 7 days, This month… or your own), clearable, disabled, min/max, a hidden input for forms; goes in <Field>. DateInput: the browser's own typed date field with the Calendar one button away; clearable adds an × once it holds a date.",
       "tags": ["date picker", "date", "range", "due date", "presets", "date input", "report period"],
       "files": ["components/ui/date-picker.jsx"]
     },
@@ -142,7 +145,7 @@
       "name": "icon",
       "type": "component",
       "title": "Icon",
-      "description": "One inline sprite of stroke glyphs; ICON_NAMES lists them. A missing glyph is added here, never drawn as an <svg> in a surface.",
+      "description": "One inline sprite of stroke glyphs; ICON_NAMES lists them. size is pixels or xs 12 · sm 14 · md 16 (the default) · lg 20 · xl 24. The sprite is fixed: a glyph it lacks is added in the template, never drawn as an <svg> in a surface.",
       "tags": ["icon", "glyph", "svg"],
       "files": ["components/ui/icon.jsx"]
     },
@@ -357,8 +360,8 @@
     {
       "name": "fixture",
       "type": "part",
-      "title": "useFixture, isSample, FixtureNotice",
-      "description": "The worked example shown while a table is empty — rows in code, never INSERTed; clearing writes nothing; a sample row carries _sample.",
+      "title": "useFixture, isSample, FixtureNotice, Examples, useExamples",
+      "description": "The worked example shown while a table is empty — examples shown only outside a Makersclaw workspace (the Examples provider, off in a workspace: there an empty table shows its live requests, LiveEmpty); rows in code, never INSERTed; clearing writes nothing; a sample row carries _sample.",
       "tags": ["example", "sample", "fixture", "empty state", "onboarding"],
       "files": ["components/parts/fixture.jsx"]
     },
@@ -369,6 +372,14 @@
       "description": "Pick a saved record or make a new one; with nothing saved it shows only New.",
       "tags": ["switcher", "picker", "saved", "records", "select"],
       "files": ["components/parts/record-switcher.jsx"]
+    },
+    {
+      "name": "live-work",
+      "type": "part",
+      "title": "LiveEmpty, LiveWork, liveWords",
+      "description": "The empty state that shows the live job, never example rows. LiveEmpty takes useRequests() and shows the request in flight on this surface or job — its line, whose request it is, Queued · after …, Answer when it needs you, Stop for the asker — with \"Rows appear here as they land\", or the app's scheduled run while it goes; with nothing in flight, the empty block (icon, title, line, one action). LiveWork is that one row; liveWords the status word (Working, Needs you, Answered, Done, Stopped, Didn't finish).",
+      "tags": ["empty state", "live", "request", "working", "needs you", "queued"],
+      "files": ["components/parts/live-work.jsx"]
     }
   ]
 }