makersclaw 0.8.0 → 0.8.2

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

@@ -1,4 +1,4 @@
-import { claw, clawBasePath, clawStream, openInDesk, publishDesk, reportError } from "./claw";
+import { claw, clawBasePath, clawNdjson, clawStream, openApp, openConnections, openFile, 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 —
@@ -18,16 +18,42 @@ import { claw, clawBasePath, clawStream, openInDesk, publishDesk, reportError }
 // 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,
+// again. `threads` / `thread` (0.8.1) read the member's own threads in
+// this app, so the app can draw its own chat with its agent (the
+// `agent-chat` block) — the same conversation the column shows, never a
+// copy. `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.
 // 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.
+// opposite of `ask`, which hands work to the app's agent. And SHOWING THE
+// LIBRARY (0.8.1): `library` reads the collections Makersclaw keeps —
+// decks, website templates, datasets — live, read-only, for a screen that
+// shows examples or a dataset. A copy into the workspace is not here: it
+// goes through the agent, with `ask`. And THE KIT (0.8.1, D15): the
+// app's jobs (`jobs`, `setJob`, `runNow`, `pauseApp`, `resumeApp`), its
+// runs (`runs`, `run`), its activity (`activity`), its accounts
+// (`connections`, `connectLink`; `openConnections` asks the desk), what
+// its agent knows and can do (`agentKit`), and a model call's price
+// before it is made (`llmEstimate`). And THE YES AND THE AGENT'S
+// QUESTIONS, IN THE APP (D18, D19): `approval` hands the facts of a yes
+// that waits on the member and the address of the Makersclaw-held press
+// frame to embed in the app's own card; `answer` answers the agent's
+// question in the chat where it was asked.
+//
+// Up to the kit this header said nothing here lists runs or activity:
+// the OS drew Agent, Runs and Activity as tabs on the window so every app
+// looked the same, and an app that drew its own would have drawn one
+// more look. The kit's blocks (schedule-card, run-history, workflow-view,
+// activity-log, connect-card, agent-kit, …) are that one look now, inside
+// the app, so the app shows its agent's work itself, beside the rows the
+// work wrote. The OS tabs stay, as the full history. What never moves
+// into the app: the yes, the account sign-in and money — the desk's.
+// The door decides who may press what (`may` on `jobs`): a block hides a
+// control the member may not use, and the door refuses it anyway.
+//
+// `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 } */
@@ -70,13 +96,21 @@ function currentSurface() {
  *   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
+ *   files      [{ name, type, data }] sent with the words (0.8.1, D27
+ *              phase 4: the `agent-pane` block's attach). `data` is a
+ *              base64 data URL (readAsDataURL). At most 4 files and 3 MB
+ *              together; the agent reads them as the desk's attachments.
+ *              `data.files_attached` in the answer is false when the ask
+ *              was taken but is queued behind another: the files did not
+ *              go, send them again once it starts.
  *
- * → { 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).
+ * → { ok: true, status, data: { ok, request, desk_origin, files_attached? } },
+ * 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), `files_too_large` (413),
+ * `too_many_files`, `bad_files` (400).
  */
-export async function ask({ text, row, how, job, list, surface, sessionId, open = true, signal } = {}) {
+export async function ask({ text, row, how, job, list, surface, sessionId, files, 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", {
@@ -90,6 +124,10 @@ export async function ask({ text, row, how, job, list, surface, sessionId, open
       list: list ?? undefined,
       surface: surface ?? currentSurface(),
       session_id: sessionId || undefined,
+      files:
+        Array.isArray(files) && files.length > 0
+          ? files.map((f) => ({ name: f?.name, type: f?.type || undefined, data: f?.data }))
+          : undefined,
     },
     signal,
   });
@@ -117,10 +155,187 @@ export function stopRequest(id) {
 
 /** 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. */
+ *  A member's press, so it opens the column even for an app that draws
+ *  its own chat (lib/claw.js openInDesk, `show`). → 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 });
+  return openInDesk({ requestId: request.id, sessionId: request.app_session_id ?? null, show: true });
+}
+
+/** GET _claw/threads → { threads: [{ session_id, request_id, title,
+ *  status, updated_at }], desk_origin }: the member's own threads in this
+ *  app, newest first — asks made from its screens or its chat. Never a
+ *  teammate's. */
+export function threads({ signal } = {}) {
+  return claw("threads", { signal });
+}
+
+/**
+ * GET _claw/threads/<session> → one of the member's threads, as the app's
+ * own chat shows it (0.8.1; the `agent-chat` block, useAgentThread):
+ *
+ *   { session_id, thread: "app" | "makersclaw",
+ *     state: "queued" | "working" | "needs_you" | "done" | "stopped" | "failed",
+ *     needs: { kind, text, at, in_app, options?, free? } | null,
+ *                  // what waits on the member. `in_app` is how the app can
+ *                  // settle it: "answer" (a question: answer(), with its
+ *                  // `options` and whether `free` words are welcome),
+ *                  // "press" (the one ask's yes: approval(), the press
+ *                  // frame), or null (on the desk)
+ *     request,                          // as _claw/requests shows one
+ *     turns: [{ id, at, member, status, writing,
+ *               parts: [{ type: "text", text } | { type: "step", label, status }] }],
+ *     desk_origin }
+ *
+ * The same conversation the desk's agent column shows: one session, two
+ * views. `member` is the member's words; `parts` the agent's text and one
+ * line per step, in order; `writing` the text being written now. Refusals:
+ * `not_your_thread` (403, a teammate's), `unknown_thread` (404). A turn
+ * typed in the app is ask({ sessionId }); a Stop is stopRequest(request.id);
+ * a question is answer(request.id, …) (0.8.1), a yes is the press frame
+ * (approval(request.id)); only what `needs.in_app` leaves null goes to the
+ * desk (openRequest).
+ *
+ * With `view: true` (0.8.1, D27: the `agent-pane` block) the answer also
+ * carries `view`, the thread as the desk's sidebar draws it:
+ *
+ *   view: { messages: [{ id, role: "user", text, files } |
+ *                      { id, role: "assistant", live, blocks }],
+ *           thinking, failure: { kind, words } | null,
+ *           questions: [{ id, prompt, options, free }] }
+ *
+ * `blocks` are the sidebar's own: text, plan, work (steps folded into
+ * "Worked through N steps", reads folded, retries fixed, helpers), approval,
+ * receipt, app, made, file, authorization. A step opens with threadCall().
+ * A claw from before `thread_view` ignores the flag and sends no `view`.
+ */
+export function thread(sessionId, { signal, view = false } = {}) {
+  return claw(`threads/${encodeURIComponent(String(sessionId ?? ""))}${view ? "?view=1" : ""}`, { signal });
+}
+
+/**
+ * GET _claw/threads/<session>/calls/<call> → { ok, call }: one step of the
+ * member's own thread, opened (0.8.1, D27; the `agent-pane` block). The
+ * digest the desk's sidebar shows under a line, bounded, never the raw
+ * input or output:
+ *
+ *   { id, line, status, reason, said,
+ *     facts: [{ label, value }], code: { label, text } | null, result }
+ *
+ * Refusals: `not_your_thread` (403), `unknown_thread` (404),
+ * `unknown_call` (404). A claw from before the door answers 404 with no
+ * `code` (`unavailable`).
+ */
+export function threadCall(sessionId, callId, { signal } = {}) {
+  const session = segment(sessionId);
+  const call = segment(callId);
+  if (!session || !call) return noId("step");
+  return claw(`threads/${session}/calls/${call}`, { signal });
+}
+
+/**
+ * GET _claw/threads/<session>/stream → the thread, pushed as the agent
+ * writes (0.8.1, D27 phase 4: "live streaming of the turn, not only
+ * polling"). `onThread(data)` gets the same object `thread(session, { view:
+ * true })` answers, after each burst of the agent's events (no legacy
+ * `turns`); `onLine()` hears every line, a ping included, as proof the
+ * stream is alive. Resolves when it ends: { ok: true, reason } with the
+ * server's reason (`settled` the turn is over, `max` open another, `gone`,
+ * `closed` eve's stream broke), or a refusal like claw()'s (`unavailable`
+ * for a claw with no stream: keep polling). Aborting resolves `aborted`.
+ * `/me` says `thread_stream: 1` where it exists.
+ */
+export async function streamThread(sessionId, { onThread, onLine, signal } = {}) {
+  const session = segment(sessionId);
+  if (!session) return noId("thread");
+  let reason = "closed";
+  const r = await clawNdjson(
+    `threads/${session}/stream`,
+    (line) => {
+      onLine?.(line);
+      if (line.type === "thread" && line.data && typeof line.data === "object") onThread?.(line.data);
+      else if (line.type === "end" && typeof line.reason === "string") reason = line.reason;
+    },
+    { signal },
+  );
+  return r.ok ? { ok: true, status: r.status, reason } : r;
+}
+
+/**
+ * GET _claw/requests/<id>/approval → the facts of a yes that waits on this
+ * member, in the SERVER's words, and the address of the press frame
+ * (0.8.1; the `approval` block, useApproval):
+ *
+ *   { ok: true,
+ *     approval: { request_id,
+ *                 question,   the agent's one question, as the server holds it
+ *                 label,      the Approve button's words ("Send 50")
+ *                 covers,     { to: { label, count }, from, then, first:
+ *                             { to, subject, body }, more, more_note } | null
+ *                 always,     the rule "Always allow this kind" would save,
+ *                             in words, or null when it is not offered
+ *                 cap_credits, at,    the request's spend cap; the version
+ *                             of the question this card is for
+ *                 frame: { src, origin },   the page to embed
+ *                 expires_at },
+ *     desk_origin }
+ *
+ * This call approves nothing. The press is the frame's: a page of
+ * Makersclaw's, in another origin, that app code cannot script, which
+ * shows these words and only counts a press a person made on a card they
+ * can see. Refusals: `not_your_request` (403, a teammate's: only the
+ * member who asked gives the yes), `unknown_request` (404),
+ * `nothing_to_approve` (409, it is not waiting on a yes any more),
+ * `not_one_yes` (409, several asks wait: the desk).
+ */
+export function approval(id, { signal } = {}) {
+  const which = segment(id);
+  if (!which) return noId("request");
+  return claw(`requests/${which}/approval`, { signal });
+}
+
+/**
+ * POST _claw/requests/<id>/answer → { ok, request }: the agent's question,
+ * answered where it was asked (0.8.1, D19). `optionId` is one of the
+ * question's options, or `text` is the member's own words where it
+ * welcomes them (`needs.free`); never both. `at` is the question's `at`
+ * from the thread: an answer to one that has moved on is refused
+ * (`moved_on`, 409). The same checks as the desk's form: the member who
+ * asked, this app's request only. Refusals carry a `code`:
+ * `not_your_request` (403), `needs_a_press` (403: a YES is never an
+ * answer; embed the `approval` block), `answer_required`,
+ * `either_option_or_text`, `unknown_option`, `no_free_text`,
+ * `text_too_long` (400), `many_questions` (409: answer on the desk),
+ * `moved_on` (409), `no_credits`/`member_cap` (402).
+ */
+export function answer(id, { optionId, text, at, answers } = {}) {
+  const which = segment(id);
+  if (!which) return noId("request");
+  // Several questions at once (0.8.1, D27: the sidebar's form): `answers`
+  // is [{ requestId, optionId | text }], one per question the view lists,
+  // sent as one resume. The door checks each against the session's own log.
+  if (Array.isArray(answers)) {
+    return claw(`requests/${which}/answer`, {
+      method: "POST",
+      body: {
+        answers: answers.map((a) => ({
+          request_id: a?.requestId,
+          option_id: typeof a?.optionId === "string" && a.optionId ? a.optionId : undefined,
+          text: typeof a?.text === "string" && a.text !== "" ? a.text : undefined,
+        })),
+        at: typeof at === "string" && at ? at : undefined,
+      },
+    });
+  }
+  return claw(`requests/${which}/answer`, {
+    method: "POST",
+    body: {
+      option_id: typeof optionId === "string" && optionId ? optionId : undefined,
+      text: typeof text === "string" && text !== "" ? text : undefined,
+      at: typeof at === "string" && at ? at : undefined,
+    },
+  });
 }
 
 /**
@@ -209,9 +424,34 @@ export function cancelJob(sessionId) {
  * 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 = llmBody(input, opts);
+  if (body.refused) return body.refused;
+  return llmAnswer(await claw("llm", { method: "POST", body, signal: opts?.signal }));
+}
+
+/**
+ * What a model call would cost, before it is made (0.8.1, the kit): POST
+ * _claw/llm with `estimate: true` and llm()'s arguments. The platform runs
+ * every check a call would (the origin, the member, the size, the input)
+ * and answers the price — never sending anything to a model, never
+ * charging. Put it on the control that spends ("Shorter · 1 cr"; the
+ * `cost` block's CostTag); useLlmAction fetches it for you.
+ *
+ * → { ok: true, estimate: { credits, credits_max } }   credits to a tenth
+ *   a refusal, as llm()'s (an empty input asks nothing of the platform)
+ *   { ok: false, unavailable: true }   a claw with no estimate yet
+ */
+export async function llmEstimate(input, opts) {
+  const body = llmBody(input, opts);
+  if (body.refused) return body.refused;
+  return llmAnswer(await claw("llm", { method: "POST", body: { ...body, estimate: true }, signal: opts?.signal }));
+}
+
+/** llm()'s body from its arguments, or `{ refused }` for one it will not
+ *  send. */
+function llmBody(input, opts) {
+  const { system, schema, maxTokens, tier, task } = opts ?? {};
+  if (!saidSomething(input)) return { refused: refused("nothing to send") };
   const body = {
     input,
     system: typeof system === "string" && system ? system : undefined,
@@ -224,9 +464,19 @@ export async function llm(input, opts) {
   try {
     JSON.stringify(body);
   } catch {
-    return refused("that cannot be sent as JSON");
+    return { refused: refused("that cannot be sent as JSON") };
   }
-  const r = await claw("llm", { method: "POST", body, signal });
+  return body;
+}
+
+/** Is there anything to send: a string with words, or a conversation? */
+export function saidSomething(input) {
+  return typeof input === "string" ? input.trim() !== "" : Array.isArray(input) && input.length > 0;
+}
+
+/** The model door's answer as it is, or a refusal for one that is not
+ *  the door's. */
+function llmAnswer(r) {
   if (!r.ok) return r;
   const answer = r.data;
   if (answer && typeof answer === "object" && !Array.isArray(answer) && typeof answer.ok === "boolean") return answer;
@@ -239,8 +489,266 @@ function refused(error) {
   return { ok: false, status: 0, error, code: "bad_input", unavailable: false };
 }
 
-export { reportError };
+/** A query string from [name, value] pairs: the ones with a value only,
+ *  names and values encoded, "" when none. A string is trimmed and an
+ *  empty one is no value; a number or a boolean is sent as its text;
+ *  anything else (null, an object) is left out. */
+function queryOf(pairs) {
+  const parts = [];
+  for (const [name, value] of pairs) {
+    const text = typeof value === "string" ? value.trim() : typeof value === "number" || typeof value === "boolean" ? String(value) : "";
+    if (text) parts.push(`${encodeURIComponent(name)}=${encodeURIComponent(text)}`);
+  }
+  return parts.length ? `?${parts.join("&")}` : "";
+}
+
+/** A page's size when it is a whole number of 1 or more, else none: the
+ *  platform cuts it to what a page may be (60 items, 100 rows). */
+const pageSize = (limit) => (Number.isInteger(limit) && limit >= 1 ? limit : undefined);
+
+/** One path segment from a collection's slug or an item's id, or null for
+ *  an id that names nothing. */
+function segment(id) {
+  const text = typeof id === "string" || typeof id === "number" ? String(id).trim() : "";
+  return text ? encodeURIComponent(text) : null;
+}
+
+/** What a library call resolves for an id that names nothing: no request
+ *  made, and not a missing door. */
+const unnamed = (error) => Promise.resolve({ ok: false, status: 0, error, unavailable: false });
+
+/**
+ * Show the Library: GET _claw/library/…, read-only, answered for the
+ * member who has the app open. The Library is Makersclaw's, not the
+ * workspace's: collections of FILES (pitch decks, PDFs, HTML website
+ * templates, graphics) and of ROWS (a dataset: investors, growth
+ * examples), each on a shelf. Every call resolves { ok, status, data } or
+ * { ok: false, status, error, unavailable, code? }, like `me`: nothing
+ * throws, and `unavailable: true` is a claw from before the door (render a
+ * quiet "not connected yet"). A copy into the workspace is the agent's,
+ * through ask(); the door never writes.
+ *
+ *   library.collections({ q, shelf })   → data { collections: [card] }
+ *   library.collection(id)              → data { collection }
+ *   library.items(id, { q, tag, cursor, limit })
+ *                                       → data { items, next_cursor, total, preview_only }
+ *   library.rows(id, { q, filters, cursor, limit })
+ *                                       → data { rows, next_cursor, total, preview_only }
+ *   library.item(id)                    → data { item, file_url?, text_excerpt? }
+ *
+ * A collection's `id` is its slug or its uuid; an item's is its uuid.
+ * `shelf` is one of decks, websites, designs, documents, datasets,
+ * examples. `filters` is { <column key>: value } for the columns the
+ * collection marks as filters (an exact match; for a tags column, has the
+ * tag), sent as f.<key>=<value>. `cursor` is the `next_cursor` of the page
+ * before, as given. Every call takes `signal`, an AbortSignal, among its
+ * options (the last argument).
+ *
+ * A paid collection on a Free plan answers `preview_only: true`, with its
+ * first few items or rows and the true `total`; an item past the preview
+ * is not listed, and library.item(id) on it is a 403 with `code:
+ * "needs_plan"`. `file_url` is a signed address, good for ten minutes:
+ * show or download from it at once, and never keep it. `preview_url` and
+ * `cover_url` are plain pictures that stay. An id that names nothing asks
+ * nothing of the platform.
+ */
+export const library = {
+  collections(opts) {
+    const { q, shelf, signal } = opts ?? {};
+    return claw(`library/collections${queryOf([["q", q], ["shelf", shelf]])}`, { signal });
+  },
+  collection(id, opts) {
+    const slug = segment(id);
+    if (!slug) return unnamed("no collection named");
+    return claw(`library/collections/${slug}`, { signal: opts?.signal });
+  },
+  items(id, opts) {
+    const slug = segment(id);
+    if (!slug) return unnamed("no collection named");
+    const { q, tag, cursor, limit, signal } = opts ?? {};
+    const query = queryOf([["q", q], ["tag", tag], ["cursor", cursor], ["limit", pageSize(limit)]]);
+    return claw(`library/collections/${slug}/items${query}`, { signal });
+  },
+  rows(id, opts) {
+    const slug = segment(id);
+    if (!slug) return unnamed("no collection named");
+    const { q, filters, cursor, limit, signal } = opts ?? {};
+    const filtered = filters && typeof filters === "object" && !Array.isArray(filters) ? Object.entries(filters) : [];
+    const query = queryOf([["q", q], ...filtered.map(([key, value]) => [`f.${key}`, value]), ["cursor", cursor], ["limit", pageSize(limit)]]);
+    return claw(`library/collections/${slug}/rows${query}`, { signal });
+  },
+  item(id, opts) {
+    const item = segment(id);
+    if (!item) return unnamed("no item named");
+    return claw(`library/items/${item}`, { signal: opts?.signal });
+  },
+};
+
+// ---------------------------------------------------------------------------
+// The kit (0.8.1, D15): the app's jobs, runs, activity, accounts and agent
+
+/** What a kit call resolves for an id that names nothing: no request
+ *  made, and not a missing door. */
+const noId = (what) => Promise.resolve({ ok: false, status: 0, error: `no ${what} named`, unavailable: false });
+
+/**
+ * GET _claw/jobs → the app's declared jobs (its wakes), as the
+ * `schedule-card` and `workflow-view` blocks draw them:
+ *
+ *   { app: { status, live },            live: the app is running (not paused)
+ *     jobs: [{ id, name, kind, topic, does, cron, tz,
+ *              words,                   "Weekdays at 07:00", or null
+ *              enabled, next_run_at, last_run_at,
+ *              last_run: { id, status, ended_at } | null,
+ *              plan }],                 the job's declared steps, or null
+ *     budget: { week_cap_credits, week_used_credits } | null,
+ *     credits,                           _claw/me's credits, as is, or null
+ *     may: { run, switch, pause } }      what this member may press
+ *
+ * `may` is the door's word, not a guess: owner, admin or the app's owner.
+ * Hide a control the member may not press; the door refuses it anyway.
+ */
+export function jobs({ signal } = {}) {
+  return claw("jobs", { signal });
+}
+
+/** PATCH _claw/jobs/<id> { enabled } → { ok, job }: switch one job on or
+ *  off. Refusals: `not_allowed` (403, below the bar), `unknown_job` (404),
+ *  409 when the job may not go live (an unlaunched app's). */
+export function setJob(id, { enabled } = {}) {
+  const job = segment(id);
+  if (!job) return noId("job");
+  return claw(`jobs/${job}`, { method: "PATCH", body: { enabled: Boolean(enabled) } });
+}
+
+/** POST _claw/run { wake_id } → { ok, run_id, wake }: run one job now,
+ *  on the member's press. Spends: say its price on the control. 403 below
+ *  the bar. */
+export function runNow(wakeId) {
+  const wake = typeof wakeId === "string" || typeof wakeId === "number" ? String(wakeId).trim() : "";
+  if (!wake) return noId("job");
+  return claw("run", { method: "POST", body: { wake_id: wake } });
+}
+
+/** POST _claw/pause → { status }: the app's Live switch off. Its jobs
+ *  stop firing until it is resumed. */
+export function pauseApp() {
+  return claw("pause", { method: "POST", body: {} });
+}
+
+/** POST _claw/resume → { status }: the app's Live switch on again. */
+export function resumeApp() {
+  return claw("resume", { method: "POST", body: {} });
+}
+
+/**
+ * GET _claw/runs → the app's runs, newest first, and their overview:
+ *
+ *   { runs: [{ id, title, status, started_at, ended_at, report,
+ *              state,          running | done | failed | stopped | needs_you
+ *              wake_id, job,   the job's id and name, or null for an ask
+ *              trigger,        schedule | manual | event | ask
+ *              by,             who pressed Run now, when manual
+ *              number,         1-based, the oldest is 1
+ *              duration_ms, credits }],
+ *     overview: { completed, failed, running, avg_ms, credits_week, cap_week_credits } }
+ *
+ * `job` narrows to one job (its wake id), `limit` to that many (at most
+ * 60). Only the jobs' runs and the member's own asks: never a
+ * teammate's ask.
+ */
+export function runs({ job, limit, signal } = {}) {
+  return claw(`runs${queryOf([["job", job], ["limit", pageSize(limit)]])}`, { signal });
+}
+
+/** GET _claw/runs/<id> → { run, steps: [{ label, status }], text, needs }:
+ *  one run's account — its steps, the agent's report, and what it waits
+ *  on (answered on the desk). 404 `unknown_run` for another app's run or
+ *  a teammate's ask. */
+export function run(id, { signal } = {}) {
+  const which = segment(id);
+  if (!which) return noId("run");
+  return claw(`runs/${which}`, { signal });
+}
+
+/** GET _claw/data/activity → { rows }: who did what in this app, newest
+ *  first. Rows: { id, at, action, surface, row_ref, detail, data, by };
+ *  `by` is `user:<email>`, `agent:<email>` (the agent on a member's ask)
+ *  or `agent:job` (on a run). `row` narrows to one record's lines (its
+ *  row_ref), `surface` to one surface, `since` (ISO or a Date) to lines
+ *  after it, `limit` 100 (at most 1,000). lib/door.js's loadActivity reads
+ *  the same lines once; this is the kit's, followed by useActivity in
+ *  lib/hooks.js. */
+export function activity({ row, surface, since, limit, signal } = {}) {
+  const after = since instanceof Date ? (Number.isNaN(since.getTime()) ? undefined : since.toISOString()) : since;
+  const query = queryOf([["row", row], ["surface", surface], ["since", after], ["limit", pageSize(limit)]]);
+  return claw(`data/activity${query}`, { signal });
+}
+
+/** GET _claw/connect → { connections: [{ key, label, toolkits, required,
+ *  connected, accounts, category, category_label }], desk_url }: the
+ *  accounts the app declares, each with whether it is connected now and
+ *  the labels of the accounts that meet it. A read: nothing is minted. */
+export function connections({ signal } = {}) {
+  return claw("connect", { signal });
+}
+
+/** POST _claw/connect { key } → { ok, key, label, toolkit, connected, url }:
+ *  the link a member opens, in a new tab, to connect one declared account
+ *  outside the desk. Connected already: no link (`url: null`). Inside the
+ *  desk ask it instead (openConnections, lib/claw.js): its panel lists
+ *  every provider of the kind. useConnections chooses for you. */
+export function connectLink(key, { signal } = {}) {
+  const need = typeof key === "string" ? key.trim() : "";
+  if (!need) return noId("account");
+  return claw("connect", { method: "POST", body: { key: need }, signal });
+}
+
+/** GET _claw/agent → what the app's agent is: { model, brief, schedule,
+ *  connections, skills: [{ name, installed }] (added on top),
+ *  own_skills: [{ name, title, when }] (the app's references),
+ *  actions: [{ name, description, agent }] (the declared actions: its
+ *  tools) }. Read by any member; adding a skill stays in the window's
+ *  Settings › Skills. */
+export function agentKit({ signal } = {}) {
+  return claw("agent", { signal });
+}
+
+export { openApp, openConnections, openFile, reportError };
 
-export const platform = { me, ask, llm, requests, stopRequest, openRequest, surfaceOfPath, startJob, cancelJob, reportError };
+export const platform = {
+  me,
+  ask,
+  llm,
+  library,
+  requests,
+  stopRequest,
+  openRequest,
+  threads,
+  thread,
+  threadCall,
+  streamThread,
+  approval,
+  answer,
+  surfaceOfPath,
+  startJob,
+  cancelJob,
+  reportError,
+  jobs,
+  setJob,
+  runNow,
+  pauseApp,
+  resumeApp,
+  runs,
+  run,
+  activity,
+  connections,
+  connectLink,
+  openConnections,
+  openApp,
+  openFile,
+  agentKit,
+  llmEstimate,
+};
 
 export default platform;

package/templates/next/template.json

@@ -20,6 +20,8 @@
       "components/ui/*",
       "components/parts/*",
       "check/run.mjs",
+      "check/automation-format.ts",
+      "check/automation-package.ts",
       "proxy.js",
       "next.config.mjs",
       "postcss.config.mjs"
@@ -56,8 +58,8 @@
     {
       "name": "notice",
       "type": "component",
-      "title": "Card, Notice, Badge, Kicker, Empty",
-      "description": "Containers and signals: Card (padding md · sm · none; titleSize md · lg), Notice (tone neutral · info · success · warning · danger), Badge (tone neutral · primary · success · warning · danger · info; variant label — small caps · soft — sentence case, every tone tinted, primary included · outline — sentence case, a hairline on no fill · code — the mono face in its own case for a version tag or a commit hash; hue 1..5 a categorical colour from --color-chart-N for kinds of things, never status: soft a hue tint with a hue dot, label filled, outline a hue hairline, the text always readable), Kicker (the small line above a heading), Empty (a search or filter with no matches).",
+      "title": "Card, ActionCard, Notice, Badge, Kicker, Empty",
+      "description": "Containers and signals: Card (padding md · sm · none; titleSize md · lg), ActionCard (one step: icon, title, description, status {tone, children} above one full-width action; stacked, never stretched to a neighbour), Notice (tone neutral · info · success · warning · danger), Badge (tone neutral · primary · success · warning · danger · info; variant label — small caps · soft — sentence case, every tone tinted, primary included · outline — sentence case, a hairline on no fill · code — the mono face in its own case for a version tag or a commit hash; hue 1..5 a categorical colour from --color-chart-N for kinds of things, never status: soft a hue tint with a hue dot, label filled, outline a hue hairline, the text always readable), Kicker (the small line above a heading), Empty (a search or filter with no matches).",
       "tags": ["card", "alert", "notice", "badge", "empty state", "status"],
       "files": ["components/ui/notice.jsx"]
     },
@@ -337,10 +339,18 @@
       "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.",
+      "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 of the window's width, or with inspectorIn frame of the body's own width between the rail and the dock: 42, 48, 64 rem; 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": "page-layout",
+      "type": "component",
+      "title": "PageLayout",
+      "description": "A screen's main area with an optional side column, taking the full height of the content it sits in (inside an AppLayout, ideally contentMode fill with no padding on the content). The main is the column that scrolls; the side is the fixed one, holding its place with its divider running top to bottom, and it is short (a summary, the next step, a few facts, a small panel; never a long form or a long list, which belong in the main). side (the side column), sideWidth px (304, 220 to 560), sideAt md · lg · xl (the page's own width from which the side sits beside the main: 42, 48, 64 rem; a measure of the page, not the window, so an open agent dock does not squeeze it; narrower, the side goes under the main in one scroll), mainLabel and sideLabel (names for a screen reader), padded (p-4 sm:p-6 on the main, p-4 on the side), fill (the main is a flex column, so a child with flex-1 grows into the height), className, mainClassName, sideClassName (spacing and tokens, never a height). Screens use it instead of a hand-drawn grid with a ruled aside, which is only as tall as its words: npm run check refuses that (rule page), and refuses a side column that holds a form or a long list (rule sidelong).",
+      "tags": ["page layout", "side column", "two column", "main and side", "split", "height", "fill", "scroll", "divider", "inspector", "aside", "master detail", "layout"],
+      "files": ["components/ui/page.jsx"]
+    },
     {
       "name": "toast",
       "type": "component",