makersclaw 0.6.0 → 0.8.0

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

@@ -2,7 +2,7 @@
 
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { claw, publishDesk, publishStatus } from "./claw";
-import { ask, cancelJob, openRequest, requests as readRequests, startJob, stopRequest } from "./platform";
+import { ask, cancelJob, llm, openRequest, requests as readRequests, startJob, stopRequest } from "./platform";
 
 // The React side of the _claw API, without any look: fetching, polling,
 // streaming and cleanup. A surface renders what comes back and owns every
@@ -17,7 +17,9 @@ import { ask, cancelJob, openRequest, requests as readRequests, startJob, stopRe
 // a request: the conversation lives in the desk's agent column, and the
 // app follows only its status. `useRequests` is the same requests seen
 // from a surface: the asks in flight on this app, so an empty table can
-// show the work coming instead of a blank.
+// 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.
 //
 // 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
@@ -672,3 +674,70 @@ export function useJob() {
 
   return { ...state, start, cancel, reset, open };
 }
+
+/** What useLlm shows with no call in flight and nothing to show. */
+const QUIET = { loading: false, result: null, error: null, unavailable: false };
+
+/**
+ * One model call from a component (lib/platform.js, llm). `run(input,
+ * opts)` takes llm()'s arguments and resolves llm()'s answer, so a caller
+ * that needs the refusal's `code` reads it there; the state is for the
+ * screen:
+ *
+ *   loading  a call is out
+ *   result   the answer when it was ok: { ok: true, text } or { ok: true,
+ *            data } (null while loading and after a failure)
+ *   error    the failure's words (null while loading, after an answer,
+ *            and on a claw with no door)
+ *   unavailable  the platform has no model door yet (a claw from before
+ *            it) or there is no network: show the quiet "not connected
+ *            yet", as for useClaw's `unavailable`. Then `error` stays
+ *            null, so a refusal and a missing door are never both set
+ *
+ * A run supersedes the one before it: that one is aborted, resolves
+ * { 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.
+ *
+ *   const { run, loading, result, error, unavailable } = useLlm();
+ *   run(`Translate to French: ${text}`, { task: "translate" });
+ *   …{loading ? <Spinner /> : result?.text}
+ */
+export function useLlm() {
+  const [state, setState] = useState(QUIET);
+  const abortRef = useRef(null);
+  const runRef = useRef(0); // the run that owns the state
+  const aliveRef = useRef(true);
+
+  // React runs this cleanup and mounts the hook again in development (its
+  // double mount; a fast refresh does the same): a call cut off by that
+  // cleanup is closed quietly in run(), below, once the answer comes back.
+  useEffect(() => {
+    aliveRef.current = true;
+    return () => {
+      aliveRef.current = false;
+      abortRef.current?.abort();
+    };
+  }, []);
+
+  const run = useCallback(async (input, opts) => {
+    abortRef.current?.abort();
+    const controller = new AbortController();
+    abortRef.current = controller;
+    const mine = ++runRef.current;
+    setState({ loading: true, result: null, error: null, unavailable: false });
+    const answer = await llm(input, { ...opts, signal: controller.signal });
+    if (runRef.current !== mine || !aliveRef.current) return answer; // a newer run owns the state, or the page is gone
+    if (controller.signal.aborted) {
+      setState(QUIET); // cut off by an unmount the hook came back from, with nothing started since
+      return answer;
+    }
+    if (answer.ok) setState({ loading: false, result: answer, error: null, unavailable: false });
+    else if (answer.unavailable) setState({ loading: false, result: null, error: null, unavailable: true });
+    else setState({ loading: false, result: null, error: answer.error || "the model did not answer", unavailable: false });
+    return answer;
+  }, []);
+
+  return { ...state, run };
+}

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

@@ -8,7 +8,9 @@ import { claw, clawBasePath, clawStream, openInDesk, publishDesk, reportError }
 // 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`).
+// can act on (`not_your_thread`, `needs_answer`, `queue_full`). `llm` is
+// the one that resolves the platform's answer as it is — { ok: true, text }
+// or { ok: true, data } — with no { status, data } around it.
 //
 // What lives here: who the app is (`me`), the error relay
 // (`reportError`), and ASKING — a screen asks its agent for work with a
@@ -20,8 +22,12 @@ import { claw, clawBasePath, clawStream, openInDesk, publishDesk, reportError }
 // 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.
+// And CALLING A MODEL (0.8.0): `llm` is one shot of text work on what is
+// on screen — sort these, draft that, translate this — answered in the
+// page, with no thread, no tools and no request on the desk. It is the
+// opposite of `ask`, which hands work to the app's agent. `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, desk_origin } */
@@ -150,8 +156,91 @@ export function cancelJob(sessionId) {
   return claw("cancel", { method: "POST", body: { session_id: sessionId } });
 }
 
+/**
+ * Call a model: POST _claw/llm. One shot of text work on what the screen
+ * holds — sort, draft, translate, summarise, pull a field out — answered
+ * here and now. Work that needs tools, the workspace or more than one
+ * step is `ask()`'s: that is the app's agent. The app never names a model
+ * (`tier` picks the size) and never holds a key; the platform meters the
+ * call to the member who made it.
+ *
+ *   input      what to work on: a string, or a conversation, [{ role:
+ *              "user" | "assistant", content }] — at most 100 messages,
+ *              none empty, the last one the user's (required)
+ *   system     how to go about it (at most 8,000 characters)
+ *   schema     a JSON Schema for the answer (an object, at most 16 KB
+ *              serialised): the answer comes back as `data`, checked
+ *              against it, not as `text`. A miss is sent back to the
+ *              model once; a second is `schema_mismatch`. No `pattern`,
+ *              `patternProperties`, `$ref`, `$defs` or `definitions`
+ *              (bad_input); nesting at most 20 levels (bad_input); at
+ *              most 1,000 parts, each object, `enum` value and listed
+ *              type (too_large). A reply too large to check against the
+ *              schema is a miss. `data` keeps keys the schema does not
+ *              name
+ *   maxTokens  the answer's ceiling, a whole number (default 1,024; over
+ *              4,096 is cut to 4,096). Sent as `max_tokens`
+ *   tier       "fast" (the default) or "smart", for the harder job
+ *   task       a short label for the usage line, /^[a-z0-9-]{1,40}$/
+ *   signal     an AbortSignal (an abort resolves { ok: false, aborted:
+ *              true })
+ *
+ * → { ok: true, text }          no schema
+ *   { ok: true, data }          with a schema
+ *   { ok: false, error, code }  a refusal, passed through as the platform
+ *     sent it (`status` and `unavailable: false` come with it). `code` is
+ *     one of, with its status:
+ *       for the member (show `error` as it is) —
+ *         no_credits 402 (the workspace wallet, a suspension, or the
+ *         Free plan's daily limit), member_cap 402 (the member's monthly
+ *         cap), app_cap 402 (the app's weekly cap), rate_limited 429
+ *         (30 calls a minute per member), model_failed 502, timeout 504
+ *         (60 s, a schema retry included; a call the clock cuts is still
+ *         charged), try_again 503, failed 500, no_member_identity 401,
+ *         not_a_member 403;
+ *       for the developer (`error` is not for the member) —
+ *         bad_input 400, too_large 413 (the body over 128 KB, or a field
+ *         over its cap), schema_mismatch 422, cross_origin 403,
+ *         not_configured 503
+ *   { ok: false, unavailable: true }  a claw from before this door (a 404
+ *     that names no refusal) or no network: render a quiet "not
+ *     connected yet", as for every door
+ *
+ * Nothing throws. An empty input asks nothing of the platform.
+ */
+export async function llm(input, opts) {
+  const { system, schema, maxTokens, tier, task, signal } = opts ?? {};
+  const said = typeof input === "string" ? input.trim() !== "" : Array.isArray(input) && input.length > 0;
+  if (!said) return refused("nothing to send");
+  const body = {
+    input,
+    system: typeof system === "string" && system ? system : undefined,
+    schema: schema && typeof schema === "object" ? schema : undefined,
+    max_tokens: typeof maxTokens === "number" ? maxTokens : undefined,
+    tier: tier || undefined,
+    task: task || undefined,
+  };
+  // claw() would read a body it cannot serialise as "not reachable".
+  try {
+    JSON.stringify(body);
+  } catch {
+    return refused("that cannot be sent as JSON");
+  }
+  const r = await claw("llm", { method: "POST", body, signal });
+  if (!r.ok) return r;
+  const answer = r.data;
+  if (answer && typeof answer === "object" && !Array.isArray(answer) && typeof answer.ok === "boolean") return answer;
+  return { ok: false, status: r.status, error: "the platform answered something unexpected", unavailable: false };
+}
+
+/** What llm() resolves for an input it will not send: the platform's own
+ *  word for it, with no request made. */
+function refused(error) {
+  return { ok: false, status: 0, error, code: "bad_input", unavailable: false };
+}
+
 export { reportError };
 
-export const platform = { me, ask, requests, stopRequest, openRequest, surfaceOfPath, startJob, cancelJob, reportError };
+export const platform = { me, ask, llm, requests, stopRequest, openRequest, surfaceOfPath, startJob, cancelJob, reportError };
 
 export default platform;

package/templates/next/files/next.config.mjs

@@ -1,3 +1,22 @@
+import { readFileSync } from "node:fs";
+
+// The app's mode, from its manifest (makersclaw.json, beside this file).
+// A browser app builds to files (output: "export"): the platform serves
+// them, and its data door answers their reads and writes. A server app
+// runs `next start`. Absent or unreadable is a server app, as every app
+// before 0.7.0 is (none has a `mode`); only the exact word "browser"
+// makes an export. `makersclaw mode` is what changes the key, never an
+// edit here.
+function mode() {
+  try {
+    const m = JSON.parse(readFileSync(new URL("./makersclaw.json", import.meta.url), "utf8"));
+    return m && m.mode === "browser" ? "browser" : "server";
+  } catch {
+    return "server";
+  }
+}
+const BROWSER = mode() === "browser";
+
 // The dashboard reaches this app at /p/<label>/ through the workspace proxy,
 // so every link and asset must carry that prefix. product_run sets
 // CLAW_BASE_PATH at build AND start time; leave it unset to run at /.
@@ -17,7 +36,8 @@
 // (src/lib/products.ts productAllowedOrigins): the product's own FQDN in
 // production, the dashboard's dev origin under a path prefix. Hardcoding a
 // localhost origin here ships an app that works in dev and refuses every
-// write in production.
+// write in production. A browser app has no Server Actions, so it takes
+// none: its writes go to the platform's data door (lib/door.js).
 const allowedOrigins = (process.env.CLAW_ALLOWED_ORIGINS || "")
   .split(",")
   .map((o) => o.trim())
@@ -28,6 +48,8 @@ const allowedOrigins = (process.env.CLAW_ALLOWED_ORIGINS || "")
 // lookups) whose Origin host is not localhost or listed here; Next 15 only
 // warned. The preview's browser is on the product host, so without this
 // every such request answers 403. Hostnames only: Next compares no port.
+// Both modes: a browser app still previews on `next dev` while it is
+// built, so CLAW_ALLOWED_ORIGINS stays its preview's rule.
 const allowedDevOrigins = [
   ...new Set(
     allowedOrigins
@@ -42,6 +64,12 @@ const allowedDevOrigins = [
 // the production build the platform made, serves and reads as its proof
 // (.next/BUILD_ID). check/run.mjs says more.
 //
+// Under output: "export" a custom distDir is where the export goes, and
+// the build then works in .next anyway (Next 16, build/index.js). So a
+// browser app is built with the default: the build in .next, the files
+// in out/, which is what the platform publishes. Its check builds in a
+// copy of the app, never in the tree.
+//
 // CLAW_TURBOPACK_ROOT is set by `npm run check` alone, when it builds a
 // copy of an app folder it cannot write (check/run.mjs buildSite). The
 // copy's node_modules is a symlink back to the app's, and Turbopack (Next
@@ -65,6 +93,11 @@ const turbopackRoot = process.env.CLAW_TURBOPACK_ROOT || "";
 // turns off, the dev overlay's /__nextjs_attach-nodejs-inspector (it
 // opens a Node debugger on loopback); only the platform can wall that
 // (CHANGELOG, 0.6.0).
+//
+// Browser mode adds three: output "export" (every page a file); images
+// unoptimized, a guard, since the export has no image server (nothing in
+// the template uses next/image); and trailingSlash false, so a page is
+// s/<key>.html, the file the platform's router looks for.
 const nextConfig = {
   basePath: process.env.CLAW_BASE_PATH || "",
   distDir: process.env.CLAW_DIST_DIR || ".next",
@@ -72,11 +105,12 @@ const nextConfig = {
     CLAW_BASE_PATH: process.env.CLAW_BASE_PATH || "",
   },
   agentRules: false,
+  ...(BROWSER ? { output: "export", images: { unoptimized: true }, trailingSlash: false } : {}),
   ...(allowedDevOrigins.length > 0 ? { allowedDevOrigins } : {}),
   ...(turbopackRoot ? { turbopack: { root: turbopackRoot }, outputFileTracingRoot: turbopackRoot } : {}),
   experimental: {
     mcpServer: false,
-    ...(allowedOrigins.length > 0 ? { serverActions: { allowedOrigins } } : {}),
+    ...(!BROWSER && allowedOrigins.length > 0 ? { serverActions: { allowedOrigins } } : {}),
   },
 };
 

package/templates/next/files/surfaces.js

@@ -7,7 +7,8 @@
  *   label      what the nav shows
  *   kind       optional, free text, one or two words for the checklist
  *              ("board", "inbox", "report") — not an enum, nothing keys on it
- *   source     the table the surface reads, when it reads one
+ *   source     the table the surface reads, when it reads one: its bare name
+ *              ("investors"), which the app's own schema answers
  *   home       true on the one surface / opens; otherwise the first entry
  *   component  the surface's component. LEAVE IT OUT while the surface is
  *              still planned: the nav shows it as planned and its page says
@@ -27,7 +28,7 @@
 // A domain surface, once built, looks like this:
 //
 //   import Investors from "./surfaces/investors";
-//   { key: "investors", label: "Investors", kind: "board", source: "public.investors", home: true, component: Investors },
+//   { key: "investors", label: "Investors", kind: "board", source: "investors", home: true, component: Investors },
 
 const surfaces = [];
 

package/templates/next/template.json

@@ -1,7 +1,7 @@
 {
   "name": "next",
   "title": "Makersclaw app (Next.js 16)",
-  "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 request proxy (proxy.js), 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.",
+  "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 company brain through the platform's data door (lib/brain.js from the browser, lib/brain-server.js for server reads), the app's own tables through the same door from the browser (lib/door.js and its hooks; a browser app's lib/data.js and lib/actions.js re-export it), 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 request proxy (proxy.js), 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",
@@ -24,11 +24,18 @@
       "next.config.mjs",
       "postcss.config.mjs"
     ],
-    "docs": ["README.md", "surfaces/README.md", "schema.sql"],
+    "docs": ["README.md", "surfaces/README.md"],
     "starter": ["app/shell.jsx", "surfaces.js"],
     "merged": ["package.json"],
     "retired": ["middleware.js"]
   },
+  "modes": {
+    "browser": {
+      "overlay": "browser",
+      "drop": ["proxy.js", "app/claw-alive/route.js", "lib/db.js", "lib/brain-server.js"],
+      "dropScripts": ["start"]
+    }
+  },
   "components": [
     {
       "name": "button",
@@ -194,7 +201,7 @@
       "name": "item",
       "type": "component",
       "title": "Item, ItemGroup",
-      "description": "The list row: media (an avatar, an image) or an icon, title, description, meta on the right, actions; href makes the whole row a link, onClick a button, neither static — actions still click on their own. aria-current, onClick, target and rel go on the row's link or button (aria-current fills the row); other props on the row. size default (56px) · sm (44px) · lg (64px); variant plain · outline · muted; layout row · stacked (a card for a grid: icon or media on top, title, description, meta at the foot, actions top-right, full cell height). ItemGroup stacks them with a rule between each (variant plain · outline).",
+      "description": "The list row: media (an avatar, an image) or an icon, title, description, meta on the right, actions; href makes the whole row a link, onClick a button, neither a plain row — actions still click on their own. aria-current, onClick, target and rel go on the row's link or button (aria-current fills the row); other props on the row. size default (56px) · sm (44px) · lg (64px); variant plain · outline · muted; layout row · stacked (a card for a grid: icon or media on top, title, description, meta at the foot, actions top-right, full cell height). ItemGroup stacks them with a rule between each (variant plain · outline).",
       "tags": ["item", "list", "row", "list item", "contact", "file", "settings row"],
       "files": ["components/ui/item.jsx"]
     },
@@ -326,6 +333,14 @@
       "tags": ["scroll", "scroll area", "overflow", "list", "carousel", "rail"],
       "files": ["components/ui/scroll-area.jsx"]
     },
+    {
+      "name": "layout",
+      "type": "component",
+      "title": "AppLayout, DocumentLayout",
+      "description": "Who owns the window's height, and who scrolls. AppLayout is the app frame, the one viewport owner (the outermost; one inside another fills its slot instead): header (the top bar, in view), navigation (a rail from md, navigationWidth px, 176; below md a Sheet behind the menu button, navigationLabel), the content (contentMode scroll: its region scrolls · fill: a bounded column for a canvas or a grid that scrolls itself; contentLabel, contentClassName for spacing, scrollKey = the route to scroll back to the top), inspector (beside the content from inspectorAt md · lg · xl, inspectorWidth px, 360, 240 to 560; below it the content and the inspector share one scroll in scroll mode, and in fill mode the inspector is a bounded pane under the content), footer (under the content, in view), height viewport · parent. In print it lets go. DocumentLayout is a page that flows, for print and export: toolbar (held at the top, never printed), width prose · page (A4) · letter · full, paper, align start · center. Nothing in an app sizes itself by the window: npm run check refuses min-h-dvh, h-screen, 100vh and h-[80vh] outside the kit.",
+      "tags": ["layout", "app frame", "shell", "viewport", "scroll", "inspector", "sidebar", "navigation", "footer", "fill", "canvas", "document", "print", "export", "page"],
+      "files": ["components/ui/layout.jsx"]
+    },
     {
       "name": "toast",
       "type": "component",

package/templates/next/files/schema.sql

@@ -1,22 +0,0 @@
--- Reference only. artifact_scaffold creates this table in the workspace
--- database when it copies the template; nothing in the app runs this file.
--- (docs/ARTIFACT-CONTRACTS.md §4)
---
--- Every write the app makes (lib/actions.js → lib/db.js logActivity) and
--- every action the artifact's agent takes (its brief tells it to insert
--- here with the sql verb) lands in this table, keyed by the artifact id
--- product_run passes as CLAW_ARTIFACT_ID. The Activity tab the OS draws on
--- the app window reads it (§9b), and so can any surface via loadActivity.
-
-create table if not exists public.artifact_activity (
-  id bigserial primary key,
-  artifact_id uuid not null,
-  at timestamptz not null default now(),
-  action text not null,          -- found, drafted, sent, replied, skipped, edited…
-  surface text,                  -- surface key
-  row_ref text,                  -- id in the surface's source table
-  detail text,                   -- one sentence
-  data jsonb not null default '{}'::jsonb,
-  by text not null default 'agent'  -- 'agent' | 'user:<email>' | 'run:<id>'
-);
-create index if not exists artifact_activity_artifact_at on public.artifact_activity (artifact_id, at desc);