makersclaw 0.7.0 → 0.8.1

package/registry/blocks/step-settings/README.md

@@ -0,0 +1,100 @@
+# StepSettings
+
+The panel for one step of an automation, made for its kind, and the panel
+for the automation as a whole. In a run the same panel is read-only and
+adds how the step went.
+
+**StepSettings** — a name; then what the kind needs, in a person's words:
+
+- **App action** — picked from the app's declared actions (`actions`),
+  with what to give it; in a team automation, which app.
+- **Connected tool** — the kind of account (mail, calendar, chat — never a
+  product), the tool, which account when there are several, what to give it.
+- **Condition** — "Go the Yes way when …"; anything else goes No.
+- **For each** — the list, at most how many, what to collect.
+- **Ask the model** — what to ask, Quick or Careful, standing instructions.
+- **Agent** — what it should do, and the most it may spend.
+- **Buy paid data** (a Zero step) — the paid service, its address, how it is
+  called (Ask, Send, Replace, Change), what to give it, and the most one call
+  may cost in dollars. Plain code: no model, and the same call is never paid
+  for twice.
+- **Set, Wait, Stop, Tell someone, Search, Another automation, Company
+  brain** — their own few fields.
+
+Every text field takes data from earlier steps (`data-picker`). For every
+step: **If it fails** (stop or carry on without it; how many tries) and a
+plain **To fix** list of what is wrong with it. In a run (`readOnly` and a
+`summary`): how it went, how many times, what it cost, what went in and
+what came out (for those who may read it), and the agent's fix (`fix-note`).
+
+**FlowSettings** — name; what it does; if it is still running when the next
+is due (skip, queue, run both); only when something changed; what happens
+when a step fails (retry, then the agent; the agent first; stop); the most
+one run may spend; what a manual run asks for first; its versions.
+
+```jsx
+import { StepSettings, FlowSettings } from "../components/blocks/step-settings";   // a Makersclaw app
+import { StepSettings, FlowSettings } from "@/components/makersclaw/blocks/step-settings";   // a shadcn project
+```
+
+`makersclaw add step-settings` lays `data-picker`, `fix-note` and
+`automation-model` with it. Client components. Each is a panel (a head, a
+scrolling body, a foot): place it beside or over the canvas.
+
+## Props
+
+### StepSettings
+
+- `step` — the step shown.
+- `available` — `availableBefore(def, step.id, stepTitle)`, plus
+  `inputs: [{ name, label }]` for a manual run's questions. `samples` —
+  `{ [stepId]: a real output }`, or null.
+- `apps` — `[{ id, name }]`; `ownedByApp` — an app's own automation needs
+  no app on an action. `actions` — `[{ name, description }]`.
+- `problems` — lines about this step (`issuesFor(issues, step.id)`).
+- `readOnly`, `summary` (a run's `summarizeSteps(rows).get(step.id)`),
+  `dataVisible` (the member may read what went in and out), `onKeepFix()`,
+  `runActions` (a node drawn under how the step went: run-view puts its
+  "Retry from this step" there).
+- `onChange(patch)` — fields to change, for `updateStep(def, id, patch)`.
+  `onRemove()` (asks first when the step holds others), `onDuplicate()`,
+  `onClose()`.
+
+### FlowSettings
+
+- `def`, `readOnly`, `versions` (`[{ version, kind, note, created_at }]`),
+  `liveVersion`, `onChange(def)`, `onClose`, `onReset` ("Reset to the app's
+  version", when it was edited from a shipped one).
+
+### The rows
+
+`TextField`, `NumberField`, `SelectField` and `SwitchField`: a labelled
+control each, on the kit's parts.
+
+## Never
+
+- Never show the definition's own keys: a step's words are a person's.
+  (The step id is shown small, because a run's rows and an app update
+  match steps by it.)
+- Never let the panel save: it only says what changed. The screen saves.
+
+## Example
+
+```jsx
+"use client";
+import { useState } from "react";
+import { availableBefore, stepTitle, updateStep } from "../components/blocks/automation-model";
+import { StepSettings } from "../components/blocks/step-settings";
+
+const START = { format: 1, key: "t", name: "T", trigger: { type: "manual" }, inputs: {}, settings: {}, steps: [{ id: "tell", kind: "notify", message: "Hello" }] };
+
+export default function Panel() {
+  const [def, setDef] = useState(START);
+  const step = def.steps[0];
+  return (
+    <div className="h-[520px] max-w-sm overflow-hidden rounded-lg border border-border">
+      <StepSettings step={step} available={availableBefore(def, step.id, stepTitle)} onChange={(patch) => setDef(updateStep(def, step.id, patch))} onClose={() => {}} />
+    </div>
+  );
+}
+```

package/registry/blocks/step-settings/block.json

@@ -0,0 +1,44 @@
+{
+  "name": "step-settings",
+  "title": "StepSettings",
+  "description": "The panel for one step of an automation, made for its kind: a name; an app action picked from the app's declared actions with what to give it; a connected tool by kind of account; a condition; a for-each's list and limit; a model call's question and tier; an agent step's instructions and credit limit; a paid-data step's service, address and price ceiling; a wait; a stop; a note for the owner; and, for every step, what happens if it fails (stop or carry on, how many tries) and a plain list of what is wrong with it. Every text field takes data from earlier steps (data-picker). In a run the same panel is read-only and shows how the step went, what went in and what came out, and what the agent changed (fix-note). FlowSettings is the panel for the automation as a whole: name, what it does, overlap, what happens when a step fails, the most a run may spend, what a manual run asks first, and its versions.",
+  "useWhen": "A step or an automation is edited or read in your own screen. automation-editor and run-view place these for you.",
+  "tags": [
+    "automation",
+    "workflow",
+    "step",
+    "settings",
+    "form",
+    "panel",
+    "inspector",
+    "action",
+    "condition",
+    "loop",
+    "llm",
+    "agent",
+    "retry",
+    "failure",
+    "versions",
+    "n8n",
+    "make"
+  ],
+  "exports": [
+    "FlowSettings",
+    "NumberField",
+    "SelectField",
+    "StepSettings",
+    "SwitchField",
+    "TextField"
+  ],
+  "files": [
+    "index.js",
+    "step-settings.jsx",
+    "flow-settings.jsx",
+    "fields.jsx"
+  ],
+  "requires": [
+    "automation-model",
+    "data-picker",
+    "fix-note"
+  ]
+}

package/registry/blocks/step-settings/demo.jsx

@@ -0,0 +1,93 @@
+"use client";
+
+// StepSettings and FlowSettings — the gallery's and the smoke test's
+// surface. Not installed into apps. A step of each kind to look at, the
+// whole-automation panel, and a failed step in a run with the agent's fix.
+import { useState } from "react";
+import { Button, ButtonGroup } from "../components/ui";
+import { StepSettings, FlowSettings } from "../components/blocks/step-settings";
+import { availableBefore, blankAutomation, stepTitle, summarizeSteps, updateStep } from "../components/blocks/automation-model";
+
+const DEF = {
+  ...blankAutomation("Morning read", "morning-read", { type: "schedule", cron: "0 7 * * 1-5", tz: "team" }),
+  does: "Reads your mail and drafts the follow-ups that are owed.",
+  steps: [
+    { id: "mail", kind: "tool", label: "Read the mail", needs: { category: "mail" }, tool: "list_messages", input: { since: "{{ trigger.at }}", limit: 200 } },
+    { id: "touches", kind: "action", action: "record_touches", input: { touches: "{{ steps.mail.output.messages }}" } },
+    { id: "check", kind: "condition", if: "{{ steps.touches.output.saved > 0 }}", then: [{ id: "tell", kind: "notify", message: "Saved some." }], else: [] },
+    { id: "ask", kind: "llm", prompt: "Write one line about {{ steps.touches.output.saved }} people.", tier: "fast" },
+    { id: "agent", kind: "agent", instructions: "Look at the list and say what looks wrong.", cap_credits: 40 },
+  ],
+};
+const ACTIONS = [
+  { name: "record_touches", description: "Save who wrote and who was met" },
+  { name: "suggest", description: "Save a draft for a person" },
+];
+const OUTPUTS = { mail: { count: 12, messages: [{ from: "ana@x.com" }] } };
+const FAILED = summarizeSteps([
+  {
+    path: "touches",
+    step_id: "touches",
+    attempt: 2,
+    status: "done",
+    started_at: "2026-10-12T07:00:01Z",
+    ended_at: "2026-10-12T07:00:04Z",
+    credits: 0.4,
+    error: null,
+    input: { touches: ["Ana@x.com "] },
+    output: { saved: 1 },
+    fix: { by: "agent", kind: "format", before: "Ana@x.com ", after: "ana@x.com", why: "The mail tool refuses spaces." },
+  },
+]).get("touches");
+
+export default function StepSettingsDemo() {
+  const [def, setDef] = useState(DEF);
+  const [id, setId] = useState("touches");
+  const [which, setWhich] = useState("step");
+  const step = def.steps.find((s) => s.id === id) ?? def.steps[0];
+  return (
+    <div className="grid gap-4 p-4">
+      <div className="flex flex-wrap gap-2">
+        <ButtonGroup aria-label="Which panel">
+          {["step", "run", "flow"].map((w) => (
+            <Button key={w} size="sm" variant={which === w ? "primary" : "secondary"} onClick={() => setWhich(w)}>
+              {w === "step" ? "A step" : w === "run" ? "A step in a run" : "The automation"}
+            </Button>
+          ))}
+        </ButtonGroup>
+        {which !== "flow" ? (
+          <ButtonGroup aria-label="Which step">
+            {def.steps.map((s) => (
+              <Button key={s.id} size="sm" variant={s.id === step.id ? "primary" : "secondary"} onClick={() => setId(s.id)}>
+                {s.kind}
+              </Button>
+            ))}
+          </ButtonGroup>
+        ) : null}
+      </div>
+      <div className="h-[640px] w-full max-w-sm overflow-hidden rounded-lg border border-border">
+        {which === "flow" ? (
+          <FlowSettings def={def} versions={[{ version: 2, kind: "member", created_at: "2026-10-11T12:00:00Z", note: "Added the check" }, { version: 1, kind: "shipped", created_at: "2026-10-09T12:00:00Z" }]} liveVersion={2} onChange={setDef} onClose={() => {}} onReset={() => {}} />
+        ) : (
+          <StepSettings
+            key={`${which}:${step.id}`}
+            step={step}
+            available={{ ...availableBefore(def, step.id, stepTitle), inputs: [] }}
+            samples={OUTPUTS}
+            actions={ACTIONS}
+            ownedByApp
+            problems={step.kind === "agent" ? ["Tell the agent what to do."] : []}
+            readOnly={which === "run"}
+            summary={which === "run" && step.id === "touches" ? FAILED : null}
+            dataVisible
+            onChange={(patch) => setDef(updateStep(def, step.id, patch))}
+            onRemove={() => setDef({ ...def, steps: def.steps.filter((s) => s.id !== step.id) })}
+            onDuplicate={() => {}}
+            onKeepFix={async () => ({ ok: true })}
+            onClose={() => {}}
+          />
+        )}
+      </div>
+    </div>
+  );
+}

package/registry/blocks/step-settings/fields.jsx

@@ -0,0 +1,58 @@
+"use client";
+
+// The plain form rows the settings panels share, on the kit's parts: a
+// labelled text, number, select or switch. Each is a real label over a
+// real control, so it works by keyboard and with a screen reader.
+
+import { useId } from "react";
+import { Field, Input, Select, Switch, Textarea } from "../../ui";
+
+export function TextField({ label, value, onChange, help, placeholder, mono = false, multiline = false, rows = 3, disabled = false }) {
+  const id = useId();
+  const common = { id, value, disabled, placeholder, className: mono ? "font-mono text-[13px]" : undefined, onChange: (e) => onChange(e.target.value) };
+  return (
+    <Field id={id} label={label} hint={help}>
+      {multiline ? <Textarea {...common} rows={rows} /> : <Input {...common} type="text" />}
+    </Field>
+  );
+}
+
+export function NumberField({ label, value, onChange, min, max, step, help, placeholder, disabled = false }) {
+  const id = useId();
+  return (
+    <Field id={id} label={label} hint={help}>
+      <Input
+        id={id}
+        type="number"
+        inputMode={step !== undefined && step < 1 ? "decimal" : "numeric"}
+        className="font-mono text-[13px]"
+        min={min}
+        max={max}
+        step={step}
+        value={value ?? ""}
+        placeholder={placeholder}
+        disabled={disabled}
+        onChange={(e) => onChange(e.target.value === "" ? undefined : Number(e.target.value))}
+      />
+    </Field>
+  );
+}
+
+export function SelectField({ label, value, onChange, options, help, disabled = false }) {
+  const id = useId();
+  return (
+    <Field id={id} label={label} hint={help}>
+      <Select id={id} value={value} disabled={disabled} options={options} onChange={(e) => onChange(e.target.value)} />
+    </Field>
+  );
+}
+
+export function SwitchField({ label, checked, onChange, help, disabled = false }) {
+  const id = useId();
+  return (
+    <div className="grid gap-0.5">
+      <Switch id={id} checked={checked} disabled={disabled} label={label} onChange={(e) => onChange(e.target.checked)} />
+      {help ? <p className="m-0 text-xs text-muted-foreground">{help}</p> : null}
+    </div>
+  );
+}

package/registry/blocks/step-settings/flow-settings.jsx

@@ -0,0 +1,115 @@
+"use client";
+
+// The panel for the automation as a whole: its name, what it does, what
+// happens when a step fails, what one run may spend, what a manual run
+// asks for first, and its versions. Props in; every change is
+// `onChange(nextDefinition)`.
+
+import { Button, Select, Input, cx } from "../../ui";
+import { Chip, Glyph, PanelSection, SidePanel, agoWords } from "../automation-model";
+import { NumberField, SelectField, SwitchField, TextField } from "./fields";
+
+const OVERLAP = [
+  { value: "skip", label: "Skip the new run" },
+  { value: "queue", label: "Queue it behind" },
+  { value: "allow", label: "Run both at once" },
+];
+const FAILURE = [
+  { value: "retry_then_agent", label: "Retry, then ask the agent to fix it" },
+  { value: "agent_first", label: "Ask the agent to fix it straight away" },
+  { value: "stop", label: "Stop the run" },
+];
+const INPUT_TYPES = [
+  { value: "string", label: "Text" },
+  { value: "number", label: "Number" },
+  { value: "boolean", label: "Yes or no" },
+  { value: "date", label: "Date" },
+];
+
+/**
+ *   def           the automation: { name, does, settings, inputs, … }
+ *   readOnly      shown, not editable
+ *   versions      [{ version, kind: shipped|member|agent, note, created_at }]
+ *   liveVersion   the version that runs
+ *   onChange(def)
+ *   onClose       draws the close button
+ *   onReset       draws "Reset to the app's version" when the automation
+ *                 was edited from a shipped one
+ */
+export function FlowSettings({ def, readOnly = false, versions = [], liveVersion = null, onChange, onClose, onReset }) {
+  const set = (patch) => onChange({ ...def, ...patch });
+  const setSettings = (patch) => onChange({ ...def, settings: { ...def.settings, ...patch } });
+  const inputs = Object.entries(def.inputs ?? {});
+  const setInputs = (next) => onChange({ ...def, inputs: Object.fromEntries(next) });
+
+  return (
+    <SidePanel glyph={<Glyph name="automation" size={20} />} title="This automation" subtitle="How it behaves as a whole" label="Flow settings" onClose={onClose}>
+      <TextField label="Name" value={def.name} disabled={readOnly} onChange={(v) => set({ name: v })} />
+      <TextField label="What it does" value={def.does ?? ""} multiline rows={3} disabled={readOnly} onChange={(v) => set({ does: v || undefined })} help="One sentence, for the list." />
+
+      <PanelSection title="When it runs">
+        <SelectField label="If it is still running when the next one is due" value={def.settings.overlap} options={OVERLAP} disabled={readOnly} onChange={(v) => setSettings({ overlap: v })} />
+        <SwitchField label="Only when something changed" checked={Boolean(def.settings.only_if_changed)} disabled={readOnly} onChange={(v) => setSettings({ only_if_changed: v })} help="Skip a scheduled run when nothing it reads has changed since the last one." />
+      </PanelSection>
+
+      <PanelSection title="When a step fails">
+        <SelectField label="What happens" value={def.settings.on_failure} options={FAILURE} disabled={readOnly} onChange={(v) => setSettings({ on_failure: v })} help="The agent changes only this run: a date format, a missing field. Never who gets what." />
+        <NumberField label="Most one run may spend" value={def.settings.run_cap_credits} min={1} disabled={readOnly} placeholder="No limit" onChange={(v) => setSettings({ run_cap_credits: v })} help="In credits. A run that reaches it stops." />
+      </PanelSection>
+
+      <PanelSection title="What a manual run asks for">
+        {inputs.length === 0 ? <p className="m-0 text-xs text-muted-foreground">Nothing. Add a question if a run needs an answer first.</p> : null}
+        {inputs.map(([name, spec], i) => (
+          <div key={i} className="flex min-w-0 items-center gap-1.5">
+            <Input
+              className="min-w-0 flex-1 font-mono text-[13px]"
+              aria-label={`Question name ${i + 1}`}
+              value={name}
+              disabled={readOnly}
+              onChange={(e) => setInputs(inputs.map((x, j) => (j === i ? [e.target.value.toLowerCase().replace(/[^a-z0-9_]/g, "_"), x[1]] : x)))}
+            />
+            <span className="w-28 shrink-0">
+              <Select aria-label={`Question type ${i + 1}`} value={spec.type} disabled={readOnly} options={INPUT_TYPES} onChange={(e) => setInputs(inputs.map((x, j) => (j === i ? [x[0], { ...x[1], type: e.target.value }] : x)))} />
+            </span>
+            {!readOnly ? (
+              <button type="button" aria-label={`Remove ${name}`} onClick={() => setInputs(inputs.filter((_, j) => j !== i))} className="inline-flex size-9 shrink-0 items-center justify-center rounded-md text-muted-foreground hover:bg-accent focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring">
+                ×
+              </button>
+            ) : null}
+          </div>
+        ))}
+        {!readOnly && inputs.length < 20 ? (
+          <Button size="sm" variant="secondary" className="justify-self-start" onClick={() => setInputs([...inputs, [`question_${inputs.length + 1}`, { type: "string", label: "" }]])}>
+            + Add a question
+          </Button>
+        ) : null}
+      </PanelSection>
+
+      {versions.length > 0 ? (
+        <PanelSection title="Versions">
+          <ol className="m-0 grid list-none gap-1.5 p-0">
+            {versions.map((v) => (
+              <li key={v.version} className={cx("grid gap-0.5 rounded-lg border px-2.5 py-1.5", v.version === liveVersion ? "border-success/50" : "border-border")}>
+                <span className="flex items-center gap-2">
+                  <b className="text-[13px] font-semibold">Version {v.version}</b>
+                  {v.version === liveVersion ? <Chip tone="green">Live</Chip> : null}
+                </span>
+                <span className="text-xs text-muted-foreground">
+                  {v.kind === "shipped" ? "From the app" : v.kind === "agent" ? "By the agent" : "Edited"}
+                  {" · "}
+                  {agoWords(v.created_at) ?? ""}
+                </span>
+                {v.note ? <p className="m-0 text-xs">{v.note}</p> : null}
+              </li>
+            ))}
+          </ol>
+          {onReset && !readOnly ? (
+            <Button size="sm" variant="secondary" className="justify-self-start" onClick={onReset}>
+              Reset to the app's version
+            </Button>
+          ) : null}
+        </PanelSection>
+      ) : null}
+    </SidePanel>
+  );
+}

package/registry/blocks/step-settings/index.js

@@ -0,0 +1,5 @@
+// The StepSettings block — `makersclaw add step-settings`. Fixed: compose
+// it through its props (README.md beside this file).
+export { FlowSettings } from "./flow-settings";
+export { NumberField, SelectField, SwitchField, TextField } from "./fields";
+export { StepSettings } from "./step-settings";