makersclaw 0.7.0 → 0.8.1

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 —
@@ -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
@@ -16,10 +18,40 @@ 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. 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.
 
@@ -64,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", {
@@ -84,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,
   });
@@ -111,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,
+    },
+  });
 }
 
 /**
@@ -150,8 +371,384 @@ export function cancelJob(sessionId) {
   return claw("cancel", { method: "POST", body: { session_id: sessionId } });
 }
 
-export { reportError };
+/**
+ * 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 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,
+    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: refused("that cannot be sent as JSON") };
+  }
+  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;
+  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 };
+}
+
+/** 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, 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;