makersclaw 0.8.0 → 0.8.2

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

@@ -0,0 +1,133 @@
+"use client";
+
+import { Icon, cx } from "../../ui";
+
+// The two marks every app draws, one of each for the whole platform
+// (the app kit, D15). Before the kit the
+// redesigns drew the agent in six different glyphs; now:
+//
+//   AgentMark  a filled diamond: the agent's work. It used tools, read
+//              and wrote, and it may cost more than one call.
+//   CallMark   a sparkle in a dashed ring: ONE model call, no
+//              conversation and no tools ("Shorter · 1 cr").
+//
+// The difference is shape (filled vs dashed), never colour alone. Byline
+// says who did a thing in words: "By the agent, on Priya's ask · 11:20".
+// No data, no door: props in.
+
+const PX = { xs: 10, sm: 12, md: 14, lg: 16 };
+const px = (size) => (typeof size === "number" ? size : PX[size] ?? PX.sm);
+
+/** A mark that names itself when `label` is given, and is decoration
+ *  (hidden from a reader) when the words beside it already say it. */
+function marked(label) {
+  return label ? { role: "img", "aria-label": label } : { "aria-hidden": true };
+}
+
+/**
+ *   label     what a screen reader hears ("The agent"); leave it out when
+ *             the words beside the mark already say it
+ *   size      xs · sm (default) · md · lg, or pixels
+ *   children  words drawn beside the mark ("Agent")
+ */
+export function AgentMark({ label, size = "sm", className, children }) {
+  const s = px(size);
+  const mark = (
+    <span {...(children ? { "aria-hidden": true } : marked(label))} className={cx("inline-flex shrink-0 text-primary", !children && className)}>
+      <Icon name="diamond" size={s} className="fill-current" />
+    </span>
+  );
+  if (!children) return mark;
+  return (
+    <span className={cx("inline-flex min-w-0 items-center gap-1", className)}>
+      {mark}
+      <span className="min-w-0">{children}</span>
+    </span>
+  );
+}
+
+/**
+ *   label     what a screen reader hears ("One model call"); leave it out
+ *             when the words beside the mark already say it
+ *   size      xs · sm (default) · md · lg, or pixels
+ *   children  words drawn beside the mark ("1 call")
+ */
+export function CallMark({ label, size = "sm", className, children }) {
+  const s = px(size);
+  const ring = s + 4;
+  const mark = (
+    <span
+      {...(children ? { "aria-hidden": true } : marked(label))}
+      style={{ width: ring, height: ring }}
+      className={cx(
+        "inline-flex shrink-0 items-center justify-center rounded-full border border-dashed border-current text-muted-foreground",
+        !children && className,
+      )}
+    >
+      <Icon name="sparkles" size={Math.max(8, s - 3)} />
+    </span>
+  );
+  if (!children) return mark;
+  return (
+    <span className={cx("inline-flex min-w-0 items-center gap-1", className)}>
+      {mark}
+      <span className="min-w-0">{children}</span>
+    </span>
+  );
+}
+
+const ISO = /^\d{4}-\d{2}-\d{2}T/;
+
+/** "11:20" for a moment today, "12 Sep" for another day; words as given. */
+function whenWords(at) {
+  if (at == null || at === "") return null;
+  const d = at instanceof Date ? at : typeof at === "string" && ISO.test(at) ? new Date(at) : null;
+  if (!d) return { words: String(at), iso: undefined };
+  if (Number.isNaN(d.getTime())) return null;
+  const now = new Date();
+  const today = d.toDateString() === now.toDateString();
+  const words = today
+    ? d.toLocaleTimeString("en-GB", { hour: "2-digit", minute: "2-digit" })
+    : d.toLocaleDateString("en-GB", { day: "numeric", month: "short" });
+  return { words, iso: d.toISOString() };
+}
+
+/** "Priya's", "James'", "your". */
+function whose(name) {
+  const n = String(name).trim();
+  if (/^you$/i.test(n)) return "your";
+  return /s$/i.test(n) ? `${n}'` : `${n}'s`;
+}
+
+/**
+ * Who did it, in words.
+ *
+ *   by     "agent" (the agent's work, its mark before it), "call" (one
+ *          model call), or a person's name
+ *   ask    whose ask the agent worked on ("Priya", or "you"); a job's run
+ *          is `ask="run"` → "on a run"
+ *   at     words ("11:20"), a Date or an ISO string
+ *   mark   false: no mark before the words (a head that already has one)
+ */
+export function Byline({ by = "agent", ask, at, mark = true, className }) {
+  const agent = by === "agent";
+  const call = by === "call";
+  const who = agent ? "By the agent" : call ? "By one model call" : `By ${by}`;
+  const on = (agent || call) && ask ? (ask === "run" ? "on a run" : `on ${whose(ask)} ask`) : null;
+  const when = whenWords(at);
+  return (
+    <span className={cx("inline-flex min-w-0 flex-wrap items-center gap-x-1.5 gap-y-0.5 text-xs text-muted-foreground", className)}>
+      {!mark ? null : agent ? <AgentMark /> : call ? <CallMark /> : null}
+      <span className="min-w-0 break-words">
+        {who}
+        {on ? `, ${on}` : ""}
+        {when ? (
+          <>
+            {" · "}
+            <time dateTime={when.iso}>{when.words}</time>
+          </>
+        ) : null}
+      </span>
+    </span>
+  );
+}

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

@@ -0,0 +1,27 @@
+{
+  "name": "agent-marks",
+  "title": "AgentMarks",
+  "description": "The platform's two marks and its byline: AgentMark, a filled diamond for the agent's work (it used tools, read and wrote, it may cost more than one call); CallMark, a sparkle in a dashed ring for one model call (a Summarize, a Shorter); and Byline, who did a thing in words (\"By the agent, on Priya's ask · 11:20\", \"By one model call\", \"By Owen\"). The two differ in shape, never colour alone, and each names itself to a screen reader when no words stand beside it.",
+  "useWhen": "Anywhere a screen holds work that was not a person's own: a value the agent wrote, a line in a timeline, a draft from one model call, the head of an ask's receipt. Use these instead of drawing a sparkle or a robot of your own, so every app marks the agent the same way. The other kit blocks (ai-action, agent-changes, activity-log, needs-you) already use them.",
+  "tags": [
+    "ai",
+    "mark",
+    "badge",
+    "byline",
+    "provenance",
+    "model call",
+    "llm",
+    "who did it",
+    "author"
+  ],
+  "exports": [
+    "AgentMark",
+    "CallMark",
+    "Byline"
+  ],
+  "files": [
+    "index.js",
+    "agent-marks.jsx"
+  ],
+  "requires": []
+}

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

@@ -0,0 +1,49 @@
+"use client";
+
+// The marks and the byline, every size and every way of saying who — the
+// gallery's and the smoke test's surface. Not installed into apps.
+import { Card } from "../components/ui";
+import { AgentMark, CallMark, Byline } from "../components/blocks/agent-marks";
+
+export default function AgentMarksDemo() {
+  const earlier = new Date(Date.now() - 3 * 24 * 3600 * 1000).toISOString();
+  return (
+    <div className="grid gap-6 p-6">
+      <Card title="The two marks">
+        <div className="grid gap-3 text-sm">
+          <div className="flex flex-wrap items-center gap-4">
+            <AgentMark size="xs" label="The agent" />
+            <AgentMark size="sm" label="The agent" />
+            <AgentMark size="md" label="The agent" />
+            <AgentMark size="lg" label="The agent" />
+            <AgentMark>Agent</AgentMark>
+          </div>
+          <div className="flex flex-wrap items-center gap-4">
+            <CallMark size="xs" label="One model call" />
+            <CallMark size="sm" label="One model call" />
+            <CallMark size="md" label="One model call" />
+            <CallMark size="lg" label="One model call" />
+            <CallMark>1 call</CallMark>
+          </div>
+          <p className="flex items-center gap-1.5">
+            <AgentMark label="Written by the agent" />
+            Head of Product at Pennant Pay
+          </p>
+        </div>
+      </Card>
+      <Card title="Bylines">
+        <div className="grid gap-2">
+          <Byline by="agent" ask="Priya" at="11:20" />
+          <Byline by="agent" ask="you" at={new Date()} />
+          <Byline by="agent" ask="run" at={earlier} />
+          <Byline by="agent" ask="James" />
+          <Byline by="call" at="09:02" />
+          <Byline by="Owen Park" at="Yesterday" />
+        </div>
+      </Card>
+      <div className="w-80 max-w-full rounded-lg border border-border p-3">
+        <Byline by="agent" ask="Anastasia Konstantinopoulou-Whitfield" at="a very long afternoon, 14 September" />
+      </div>
+    </div>
+  );
+}

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

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

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

@@ -0,0 +1,234 @@
+# AgentPane
+
+The desk's agent sidebar, as the app's own pane, in the app's theme (0.8.1,
+D27). It replaces `agent-chat`: the founder found that chat "not on par
+with the desk agent sidebar, in terms of tool calls, questions, showing
+information", so this is the sidebar, not a smaller chat.
+
+It shows what the sidebar shows:
+
+- the member's words, and the agent's text as it is written;
+- the **plan**, a checklist that ticks as the agent works;
+- the **work**, folded: the steps between two things the agent said are one
+  line, "Worked through 26 steps" (or the step running now, with a
+  spinner); open it for one line per step, each with a mono tag, what it
+  did in words, and a word for how it ended. **Open a step** for its facts,
+  the command or statement worth reading, what came back, and why it
+  failed;
+- reads folded ("Read 6 files"), retries a later call fixed ("Fixed 2
+  issues on the way"), the same line again ("Checked on the build · 5
+  times"), a failure nothing fixed with its few plain words, and a card of
+  **helpers** started side by side;
+- the agent's **questions** as one form: several at once, options as
+  chips, a box for the member's own words, one submit; an answered one
+  shrinks to a line;
+- the one ask's **yes** as the `approval` block's press frame (`yes`);
+- what it **made**: an app, files, addresses;
+- the **past chats** (a dot on those that need you or work), New chat,
+  Stop ("Stopping…" after the press), "You stopped it", "It stopped before
+  finishing" in plain words, jump to latest.
+
+It is the same conversation the desk's sidebar shows: one session, two
+views. The lines and what they say are decided by the platform, with the
+rules the sidebar runs, and sent as data; this block draws them and nothing
+else. So a new tool the platform learns to describe reads right in every
+app at once, with no change here.
+
+```jsx
+import { AgentPane } from "../components/blocks/agent-pane";   // a Makersclaw app ("./blocks/agent-pane" from components/)
+import { AgentPane } from "@/components/makersclaw/blocks/agent-pane";   // a shadcn project
+```
+
+A client component. It draws the object `useAgentPane()` returns
+(lib/hooks.js); asking stays with the hook. The Example is at the end.
+
+## The frame is `chat-pane`
+
+The head (title, New chat, Chats, close), the empty state, the scroll, the
+message box and a starting line from the dock are the `chat-pane` block
+(X5): the desk's chat pane, ported. This block is what the **agent** puts in
+it: the lines (plan, folded work, questions, what it made) and the bar of what
+waits on the member. `AgentPane` is `ChatPane` with those inside, so every
+app that draws `AgentPane` has the desk's message box: the words on top, + to
+attach and a round send under them, the microphone beside it, a round stop in
+the send's place while a turn runs.
+
+## Follow-ups are the same conversation
+
+A message after a Stop, a finished ask or a failed turn goes on in the
+same session and the same request (D29): the platform opens the closed
+request again, so there is no second card and nothing jumps. The pane
+sends every message with the thread's session (`useAgentPane` never starts
+a fresh one for it) and says "Ask a follow-up…" once a thread exists.
+Only a plan or a piece of one, a change the agent sent up, a counted job
+and a hand-off that never started get a new request; for those
+`chat.sameConversation` is false and the box keeps the app's own words.
+
+## Questions keep the conversation open
+
+While a question waits, the main composer stays available. Sending there
+skips that question and continues the same thread, including attachments.
+Answering the question removes it immediately while the answer is sent; a
+failed submission restores it for retry. Stale thread reads cannot bring an
+accepted question back, but a new question still appears. Approval, account
+connection and credit-limit gates keep their existing controls.
+
+## Tell the desk
+
+An app that places this block says so in its package: `"agent_pane": true`
+in `store.json`'s `seeds.blueprint` (a built app: in its blueprint). The
+desk then draws no agent sidebar for the app's window: no column, no Agent
+tab. The pane is the conversation. Without the flag the desk keeps its
+sidebar, and the member sees two agent panes.
+
+## What the app controls
+
+- **Where it sits**: in the app's `agent-dock` (a column beside the work, the
+  desk's own shape; one per app, in the shell). Inside a dock the head's close
+  folds the column with no `onClose` from you. A compact card in a column of
+  its own is also fine (`fill={false}`). Do not put the shell's agent in a
+  modal `Sheet` that dims the work: that is what the dock replaced. `bare`
+  drops the head.
+- **What it is about**: `useAgentPane({ row })`. `row` is the record on
+  screen (`{ kind, id, name }`); it rides with every ask as context and the
+  thread is kept for that record. `how` is one sentence for the agent only.
+  The ask is `chat.send(text)`, so an Ask button, an ask bar or a chip all
+  start or continue the same conversation.
+- **Its first line**: a button that says the agent will do the work calls
+  `openAgent("Draft a project plan for me")` (blocks/agent-dock). The pane
+  inside the dock sends that line in a new chat and the agent asks only for
+  what it is missing; no form first (X9).
+- **Its words**: `title`, `empty`, `suggestions`, `placeholder`, `hint`.
+- **Nothing else.** No colour props: the app's theme paints it.
+
+## Props
+
+- `chat` — what `useAgentPane()` 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.
+- `empty` — one line before the first ask. Say what the agent can do here,
+  in the app's words.
+- `placeholder` — the box's words. Default `"Ask anything…"`.
+- `hint` — a quiet line under the box.
+- `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)`.
+- `mark` — a node before the agent's turns (the app's mark). Default none.
+- `onOpen` — `({ kind: "app", id } | { kind: "file", path, where, appRef })`:
+  the Open of something it made. Default: `chat.open` (the desk opens it).
+- `onClose` — a close in the head. Inside an `agent-dock` it is the dock's
+  own (the column folds) unless you give one.
+- `recent` — how many past chats the empty state lists before the first ask,
+  with an "All N chats" link past that. Default `5`; `0` lists none. With no
+  chats yet it says "No chats yet. Your first message starts one." The head
+  always has New chat and Chats.
+- `bare` — no head, inside a `Sheet` or a `Card` that has its own.
+- `fill` — default `true`: the pane takes its container's height and the
+  thread scrolls inside it. `false`: a compact pane for a card in a column;
+  once a thread starts it scrolls inside a capped height.
+- `className` — layout around it. Never colour.
+
+## useAgentPane (lib/hooks.js)
+
+```js
+const chat = useAgentPane({ row, how, job, key });
+```
+
+It is `useAgentThread` with the sidebar's view, plus the Chats list and a
+step's detail. It returns everything `useAgentThread` returns (`sessionId`,
+`state`, `needs`, `pending`, `place`, `request`, `sending`, `loading`,
+`error`, `unavailable`, `send`, `stop`, `answer`, `openOnDesk`, `newChat`,
+`reload`), and:
+
+- `view` — `{ messages, thinking, failure, questions }`: the thread as the
+  sidebar draws it. A claw from before the view sends none; the pane then
+  draws the small turns plainly.
+- `chats` — `{ items: [{ sessionId, title, mark, at }], loading, error,
+  unavailable }`, the member's own threads in this app.
+- `openSession(sessionId)` — switch to one of them.
+- `callDetail(callId)` — one step, opened: `{ facts, code, result, reason,
+  said }`, asked when a member opens a step, never carried with the line.
+- `answer({ answers: [{ requestId, optionId | text }] })` — every question
+  the view lists, as one resume.
+- `openRequest(requestId)` — "Open in Makersclaw" under a change the agent
+  sent up.
+
+It reads `GET _claw/threads/<session>?view=1` and `GET _claw/threads` (lib/
+platform.js `thread`, `threads`), the member's own threads in this app,
+never a teammate's, and streams a working thread (`streamThread`). It looks
+every 1.5 s while the agent works and no stream is alive, every 6 s while
+it waits on the member, and not at all once the turn has ended or the page
+is hidden. No tool's input or output is ever sent; a step's detail is
+a bounded digest.
+
+## The composer, the stream, the press, Open
+
+- **Files.** The + in the box, paste and drop attach up to 4 files and 3 MB
+  together; they go with the words (`chat.send(text, { files })`, `ask({
+  files })`) as the desk's attachments. A message that is queued behind
+  another goes without them, and `chat.notice` says so.
+- **Voice.** A microphone button dictates into the box with the browser's
+  speech recognition; it is not drawn where the browser has none.
+- **Stop.** While a turn runs and the box is empty, a round stop takes the
+  send arrow's place (a message typed then waits its turn: the arrow comes
+  back). "Stopping…" after the press.
+- **Live.** A working thread is streamed (`GET _claw/threads/<session>/
+  stream`): text and steps appear as they are written. The poll looks
+  rarely while the stream is alive and takes over if it ends or the claw
+  has none.
+- **The yes, for a tool too.** `yes` is drawn whenever `chat.needs.in_app`
+  is `"press"`: the one ask's yes, or one parked tool call (the card says
+  what it will do and shows its command). Several calls parked together
+  stay on the desk.
+- **Open.** Under an app or a file it made, Open asks the desk to open it
+  (`chat.open`); `onOpen` overrides.
+
+## Outside Makersclaw
+
+Any object of the same shape works: `view` (`messages` of `{ id, role:
+"user", text, files }` or `{ id, role: "assistant", live, blocks }`), the
+fields above, and the functions.
+
+## Example
+
+A pane about the person a screen has open, beside the record.
+
+```jsx
+"use client";
+import { useAgentPane } from "../lib/hooks";
+import { AgentPane } from "../components/blocks/agent-pane";
+
+export default function PersonAsk({ person }) {
+  const chat = useAgentPane({ row: { kind: "person", id: person.id, name: person.name } });
+  return (
+    <AgentPane
+      chat={chat}
+      title={`Ask about ${person.name}`}
+      suggestions={["What did we last talk about?", "Draft a follow-up"]}
+    />
+  );
+}
+```
+
+With the yes pressed in the approval card above the box:
+
+```jsx
+"use client";
+import { useAgentPane, useApproval } from "../lib/hooks";
+import { AgentPane } from "../components/blocks/agent-pane";
+import { Approval } from "../components/blocks/approval";
+
+export default function Ask() {
+  const chat = useAgentPane();
+  // Only for the one ask's yes; useApproval(null) asks nothing.
+  const approval = useApproval(chat.needs?.in_app === "press" ? chat.request?.id : null);
+  return (
+    <AgentPane
+      chat={chat}
+      yes={<Approval approval={approval} title="Waiting for your yes" onOpenDesk={chat.openOnDesk} />}
+    />
+  );
+}
+```