makersclaw 0.8.0 → 0.8.1

package/registry/blocks/agent-changes/agent-changes.jsx

@@ -0,0 +1,118 @@
+"use client";
+
+import { useState } from "react";
+import { Button, Icon, cx } from "../../ui";
+import { AgentMark, Byline } from "../agent-marks";
+
+// AgentChanges — the receipt of one ask (the app kit, D15): what the
+// agent did in one line ("Sorted 46 stickies into 6 groups"), the changes
+// listed (folded after five), and "Undo this ask". The block draws; the
+// app's own declared undo action does the work, because only the app
+// knows what an ask drew (Whiteboard's "violet trace", Mind Maps, Gantt's
+// "Undo draft"). The list comes from useActivity({ agent: true, since })
+// or from what the ask reported. Props in, callbacks out.
+
+const FOLD = 5;
+
+/**
+ *   summary    what the ask did, one line ("Sorted 46 stickies into 6 groups")
+ *   changes    [{ id?, label, detail? }]: each change, newest last;
+ *              folded after five
+ *   by         who and when: Byline's props ({ by, ask, at }), or words
+ *   onUndo()   async → { ok } | { ok: false, error }: the app's undo of
+ *              this ask; without it there is no Undo (the member may not)
+ *   undone     true when the ask was undone already (from your data)
+ *   undoLabel  default "Undo this ask"
+ *   undoneWords default "Undone. Everything this ask changed is back as it was."
+ *   label      the region's name for a reader (default the summary)
+ */
+export function AgentChanges({
+  summary,
+  changes = [],
+  by,
+  onUndo,
+  undone: undoneProp = false,
+  undoLabel = "Undo this ask",
+  undoneWords = "Undone. Everything this ask changed is back as it was.",
+  label,
+  className,
+}) {
+  const [open, setOpen] = useState(false);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState(null);
+  const [undoneHere, setUndoneHere] = useState(false);
+  const undone = undoneProp || undoneHere;
+  const list = (changes ?? []).filter(Boolean);
+  const shown = open ? list : list.slice(0, FOLD);
+  const more = list.length - shown.length;
+
+  async function undo() {
+    if (!onUndo || busy) return;
+    setBusy(true);
+    setError(null);
+    let r;
+    try {
+      r = await onUndo();
+    } catch (e) {
+      r = { ok: false, error: e?.message ?? String(e) };
+    }
+    setBusy(false);
+    if (r && r.ok === false) setError(r.error || "Couldn't undo it. Try again.");
+    else setUndoneHere(true);
+  }
+
+  return (
+    <section
+      aria-label={label ?? (typeof summary === "string" ? summary : "What the agent changed")}
+      className={cx("@container grid grid-cols-1 min-w-0 content-start gap-2.5 rounded-lg border border-border bg-card p-3.5 text-sm text-card-foreground", undone && "bg-muted", className)}
+    >
+      <div className="flex min-w-0 items-start gap-2">
+        <span className="mt-1 shrink-0">
+          <AgentMark label="The agent" />
+        </span>
+        <div className="grid grid-cols-1 min-w-0 flex-1 gap-0.5">
+          <p className={cx("min-w-0 break-words font-semibold", undone && "text-muted-foreground line-through")}>{summary}</p>
+          {by ? typeof by === "object" && !Array.isArray(by) && !by.$$typeof ? <Byline mark={false} {...by} /> : <span className="text-xs text-muted-foreground">{by}</span> : null}
+        </div>
+      </div>
+
+      {list.length ? (
+        <ul className={cx("m-0 grid grid-cols-1 list-none gap-1 p-0 pl-5", undone && "text-muted-foreground")}>
+          {shown.map((c, i) => (
+            <li key={c.id ?? i} className="flex min-w-0 items-start gap-2">
+              <Icon name={undone ? "undo" : "check"} size={12} className={cx("mt-1 shrink-0", undone ? "text-muted-foreground" : "text-success")} />
+              <span className="min-w-0 break-words">
+                <span className={undone ? "line-through" : undefined}>{c.label}</span>
+                {c.detail ? <span className="text-muted-foreground"> · {c.detail}</span> : null}
+              </span>
+            </li>
+          ))}
+        </ul>
+      ) : null}
+      {list.length > FOLD ? (
+        <Button variant="link" size="inherit" tone="muted" className="justify-self-start pl-5 text-xs" aria-expanded={open} onClick={() => setOpen((v) => !v)}>
+          {open ? "Show fewer" : `Show ${more} more`}
+        </Button>
+      ) : null}
+
+      {undone ? (
+        <p role="status" className="flex items-center gap-1.5 text-xs text-muted-foreground">
+          <Icon name="undo" size={14} className="shrink-0" />
+          {undoneWords}
+        </p>
+      ) : onUndo ? (
+        <div className="flex min-w-0 flex-wrap items-center gap-2">
+          <Button size="sm" variant="secondary" loading={busy} onClick={undo}>
+            <Icon name="undo" size={14} /> {undoLabel}
+          </Button>
+          {list.length ? <span className="text-xs text-muted-foreground">{list.length === 1 ? "takes it back" : `takes back all ${list.length} changes`}</span> : null}
+        </div>
+      ) : null}
+      {error ? (
+        <p role="alert" className="text-xs text-destructive">
+          {error}
+        </p>
+      ) : null}
+    </section>
+  );
+}

package/registry/blocks/agent-changes/block.json

@@ -0,0 +1,28 @@
+{
+  "name": "agent-changes",
+  "title": "AgentChanges",
+  "description": "The receipt of one ask: what the agent did in one line (\"Sorted 46 stickies into 6 groups\"), who asked and when, the changes listed (folded after five, \"Show 41 more\"), and \"Undo this ask\" — your async undo, the app's own declared action, answering { ok } — then the undone state, struck through, in words. The block draws; the app knows what an ask changed and takes it back.",
+  "useWhen": "After the agent changes many things at once on a member's ask and the member should see them and take them all back in one press: a whiteboard sorted into groups, a mind map grown, a plan drafted onto a Gantt, a batch of records tidied. Not for proposals waiting to be kept (suggestion) or for the app's whole history (activity-log).",
+  "tags": [
+    "undo",
+    "changes",
+    "receipt",
+    "ask",
+    "what changed",
+    "revert",
+    "trace",
+    "batch",
+    "summary",
+    "history"
+  ],
+  "exports": [
+    "AgentChanges"
+  ],
+  "files": [
+    "index.js",
+    "agent-changes.jsx"
+  ],
+  "requires": [
+    "agent-marks"
+  ]
+}

package/registry/blocks/agent-changes/demo.jsx

@@ -0,0 +1,39 @@
+"use client";
+
+// AgentChanges for a big ask (folded), a small one, an undo that fails,
+// one already undone, and one the member may not undo — the gallery's and
+// the smoke test's surface. Not installed into apps.
+import { AgentChanges } from "../components/blocks/agent-changes";
+
+const GROUPS = ["Pricing", "Onboarding", "Scheduling", "Reports", "Mobile", "Integrations"];
+const MOVES = Array.from({ length: 46 }, (_, i) => ({ id: `m${i}`, label: `Sticky ${i + 1}`, detail: `to ${GROUPS[i % GROUPS.length]}` }));
+
+const later = (r, ms = 700) => () => new Promise((res) => setTimeout(() => res(r), ms));
+
+export default function AgentChangesDemo() {
+  return (
+    <div className="grid gap-6 p-6 [grid-template-columns:repeat(auto-fit,minmax(min(100%,20rem),1fr))]">
+      <AgentChanges summary="Sorted 46 stickies into 6 groups" by={{ ask: "Priya", at: "11:20" }} changes={MOVES} onUndo={later({ ok: true })} />
+      <AgentChanges
+        summary="Drafted the launch plan onto the chart"
+        by={{ ask: "you", at: new Date() }}
+        changes={[
+          { label: "Beta invites", detail: "Mon 3 Nov – Fri 7 Nov" },
+          { label: "Press kit", detail: "Tue 4 Nov – Thu 13 Nov" },
+          { label: "Launch day", detail: "Tue 18 Nov" },
+        ]}
+        onUndo={later({ ok: false, error: "Two of these bars were moved by Owen since. Undo them one by one." })}
+      />
+      <AgentChanges summary="Grew the Pricing branch by 5 ideas" by={{ ask: "run", at: "07:00" }} changes={MOVES.slice(0, 5)} undone />
+      <AgentChanges summary="Tidied 12 company names" by="By the agent, on Owen's ask · yesterday" changes={[{ label: "ACME corp → Acme Corp" }]} />
+      <div className="w-80 max-w-full">
+        <AgentChanges
+          summary="Merged Harborview Hospitality Group and Harborview Hospitality Group Ltd, a duplicate found in last week's import"
+          by={{ ask: "Anastasia", at: "09:05" }}
+          changes={[{ label: "Kept the older record, with every note and deal from both" }]}
+          onUndo={later({ ok: true })}
+        />
+      </div>
+    </div>
+  );
+}

package/registry/blocks/agent-changes/index.js

@@ -0,0 +1,3 @@
+// The AgentChanges block — `makersclaw add agent-changes`. Fixed: compose
+// it through its props (README.md beside this file).
+export { AgentChanges } from "./agent-changes";

package/registry/blocks/agent-chat/README.md

@@ -0,0 +1,145 @@
+# AgentChat
+
+The app's own chat with its agent, drawn in the app's look. The member
+types; the agent's answer appears as it is written, with one line per
+step it takes ("Searching the web"), folded into "Worked through 6 steps"
+once the turn ends. Stop is one press away while it works.
+
+It is the same conversation the desk's agent column shows: one session,
+two views, never a copy. A member who opens the column on the desk reads
+the same thread, and either place can continue it.
+
+What waits on the member is settled in the chat, where it was asked:
+
+- **The agent's question** is answered in place (0.8.1, D19): its options,
+  one press each, and a box for the member's own words where the question
+  welcomes them (`chat.answer`). The same checks as the desk's form.
+- **The agent's yes** is the `approval` block's press frame, handed in as
+  `yes`. The chat never draws an Approve of its own: the press is
+  Makersclaw's, in a frame the app's code cannot script. Without `yes` the
+  chat says "Waiting for your yes on the desk" with the agent's words and
+  "Open on the desk".
+- **Connecting an account**, and **money**: on the desk, always, and
+  several questions at once.
+
+```jsx
+import { AgentChat } from "../components/blocks/agent-chat";   // a Makersclaw app ("./blocks/agent-chat" from components/)
+import { AgentChat } from "@/components/makersclaw/blocks/agent-chat";   // a shadcn project
+```
+
+A client component. It draws the object `useAgentThread()` returns
+(lib/hooks.js); asking stays with the hook. The Example is at the end.
+
+## Tell the desk
+
+An app that places this block says so in its package: `"agent_in_app":
+true` in `store.json`'s `seeds.blueprint` (a built app: in its
+blueprint). The desk then keeps its agent column folded for the app, and
+an ask from the app's screens never opens the column by itself; the
+column still opens from the window's Show agent control, on the same
+thread. Without the flag the desk opens its column on every ask, as it
+did before, and the member sees two agent panes.
+
+## Props
+
+- `chat` — what `useAgentThread()` returns. Required.
+- `title` — the head's words, and the box's label. Default `"Ask the
+  agent"`. About a record: `"Ask about Pinewood"`.
+- `suggestions` — asks that fit the moment, as chips before the first ask.
+  A chip sends its words. Long ones wrap; they never run off the column.
+- `empty` — one line before the first ask. Say what the agent can do here,
+  in the app's words. Never where the answer appears: it appears here.
+- `placeholder` — the box's words. Default `"Ask anything…"`.
+- `yes` — a node drawn in place of the bar when the agent waits on a yes
+  the app can take (`chat.needs.in_app === "press"`): the `approval`
+  block, fed by `useApproval(chat.request.id)`. Hook it only for that
+  need: `useApproval(chat.needs?.in_app === "press" ? chat.request?.id : null)`.
+- `onClose` — a close in the head, for a panel beside a record.
+- `bare` — no head, inside a `Sheet` or a `Card` that has its own.
+- `fill` — default `true`: the chat takes its container's height (a
+  panel, a sheet) and the thread scrolls inside it. `false`: a compact
+  chat for a card in a column (an inspector, a home screen's side): it is
+  as tall as its content, and once a thread starts it scrolls inside a
+  capped height.
+- `className` — layout around it. Never colour.
+
+## useAgentThread (lib/hooks.js)
+
+```js
+const chat = useAgentThread({ row, how, job, key });
+```
+
+- `row` — the record the chat is about, `{ kind, id, name }`. It rides
+  with every ask as context, and the thread is kept for it: open the same
+  record again and its chat is there.
+- `how` — instructions for the agent only.
+- `job` — a declared job's key, or `true`. Default none: a chat is a
+  conversation, not a job.
+- `key` — where this browser keeps the thread (default the row's
+  `kind:id`, else `"app"`); `null` keeps none.
+
+It returns `sessionId`, `state` (`queued` · `working` · `needs_you` ·
+`done` · `stopped` · `failed`, or null before the first ask), `needs`
+(`{ kind, text, at, in_app, options?, free? }` while it waits on the
+member: `in_app` is `"answer"`, `"press"` or null for the desk), `turns`, `pending`,
+`place` (`"makersclaw"` for an ask made in Makersclaw: the chat shows a
+pointer, not the turns), `request`, `sending`, `loading`, `error`,
+`unavailable`, and `send(text)`, `stop()`, `answer({ optionId | text })`,
+`openOnDesk()`, `newChat()`, `reload()`.
+
+It reads `GET _claw/threads/<session>` (lib/platform.js `thread`): the
+member's own thread in this app, never a teammate's. It looks every
+1.5 s while the agent works, every 6 s while it waits on the member, and
+not at all once the turn has ended or the page is hidden.
+
+## Outside Makersclaw
+
+Any object of the same shape works: `turns` (`[{ id, member, parts:
+[{ type: "text", text } | { type: "step", label, status }], writing,
+status }]`), `state`, `needs`, `pending`, and the five functions.
+
+## Example
+
+A chat about the person a screen has open, beside the record.
+
+```jsx
+"use client";
+import { useAgentThread } from "../lib/hooks";
+import { AgentChat } from "../components/blocks/agent-chat";
+
+export default function PersonAsk({ person }) {
+  const chat = useAgentThread({ row: { kind: "person", id: person.id, name: person.name } });
+  return (
+    <AgentChat
+      chat={chat}
+      title={`Ask about ${person.name}`}
+      suggestions={["What did we last talk about?", "Draft a follow-up"]}
+    />
+  );
+}
+```
+
+On a home screen, the same chat as a card in the side column: `fill={false}` and `bare`
+inside a `Card` that has its own title.
+
+A chat that settles what waits on the member in place: the question
+answered in the chat, the yes pressed in the approval card above it.
+
+```jsx
+"use client";
+import { useAgentThread, useApproval } from "../lib/hooks";
+import { AgentChat } from "../components/blocks/agent-chat";
+import { Approval } from "../components/blocks/approval";
+
+export default function Ask() {
+  const chat = useAgentThread();
+  // Only for the one ask's yes; useApproval(null) asks nothing.
+  const approval = useApproval(chat.needs?.in_app === "press" ? chat.request?.id : null);
+  return (
+    <AgentChat
+      chat={chat}
+      yes={<Approval approval={approval} title="Waiting for your yes" onOpenDesk={chat.openOnDesk} />}
+    />
+  );
+}
+```