@graph8/sdk 0.308.1 → 0.357.0

package/blocks/workflows/block.json

@@ -0,0 +1,188 @@
+{
+  "$schema": "../block.schema.json",
+  "id": "workflows",
+  "title": "Workflows",
+  "summary": "Workflow list, step-list editor, trigger configuration and run history with pause, resume, stop and restart.",
+  "features": [
+    "workflow list with run preview, run, enable and delete",
+    "ordered step editor for linear workflows",
+    "trigger type, interval and cursor reset",
+    "run history with polled detail and run controls"
+  ],
+  "dependsOn": [
+    "foundation"
+  ],
+  "operations": [
+    "list_workflows_workflows_get",
+    "create_workflow_workflows_post",
+    "plan_workflow_workflows__action_id__plan_post",
+    "execute_workflow_workflows__action_id__execute_post",
+    "update_workflow_workflows__action_id__put",
+    "delete_workflow_workflows__action_id__delete",
+    "get_workflow_workflows__action_id__get",
+    "get_node_types_schema_workflows_node_types_schema_get",
+    "get_trigger_status_workflows__action_id__trigger_status_get",
+    "reset_trigger_cursor_workflows__action_id__trigger_reset_post",
+    "list_workflow_executions_workflows_executions_get",
+    "get_execution_workflows_executions__execution_id__get",
+    "pause_execution_workflows_executions__execution_id__pause_post",
+    "resume_execution_workflows_executions__execution_id__resume_post",
+    "stop_execution_workflows_executions__execution_id__stop_post",
+    "restart_execution_workflows_executions__execution_id__restart_post"
+  ],
+  "components": [
+    {
+      "name": "WorkflowList",
+      "file": "components/workflow-list.tsx",
+      "purpose": "Workflows with run (plan preview and JSON input behind a confirm), enable or disable, create and delete.",
+      "operations": [
+        "list_workflows_workflows_get",
+        "create_workflow_workflows_post",
+        "plan_workflow_workflows__action_id__plan_post",
+        "execute_workflow_workflows__action_id__execute_post",
+        "update_workflow_workflows__action_id__put",
+        "delete_workflow_workflows__action_id__delete"
+      ],
+      "tiers": [
+        "read",
+        "external",
+        "destructive"
+      ]
+    },
+    {
+      "name": "WorkflowEditor",
+      "file": "components/workflow-editor.tsx",
+      "purpose": "Edit a workflow as an ordered list of steps: names, JSON configs, and add, move or remove steps on linear graphs; save behind a confirm.",
+      "operations": [
+        "get_workflow_workflows__action_id__get",
+        "get_node_types_schema_workflows_node_types_schema_get",
+        "update_workflow_workflows__action_id__put"
+      ],
+      "tiers": [
+        "read",
+        "external"
+      ]
+    },
+    {
+      "name": "TriggerConfig",
+      "file": "components/trigger-config.tsx",
+      "purpose": "Trigger type, polling interval and filters with the live trigger status and a reset-cursor action, both behind a confirm.",
+      "operations": [
+        "get_workflow_workflows__action_id__get",
+        "get_trigger_status_workflows__action_id__trigger_status_get",
+        "get_node_types_schema_workflows_node_types_schema_get",
+        "update_workflow_workflows__action_id__put",
+        "reset_trigger_cursor_workflows__action_id__trigger_reset_post"
+      ],
+      "tiers": [
+        "read",
+        "external"
+      ]
+    },
+    {
+      "name": "RunHistory",
+      "file": "components/run-history.tsx",
+      "purpose": "Runs with a status filter, a polled run detail, and pause, resume, stop and restart behind a confirm.",
+      "operations": [
+        "list_workflow_executions_workflows_executions_get",
+        "get_execution_workflows_executions__execution_id__get",
+        "pause_execution_workflows_executions__execution_id__pause_post",
+        "resume_execution_workflows_executions__execution_id__resume_post",
+        "stop_execution_workflows_executions__execution_id__stop_post",
+        "restart_execution_workflows_executions__execution_id__restart_post"
+      ],
+      "tiers": [
+        "read",
+        "external"
+      ]
+    }
+  ],
+  "hooks": [
+    {
+      "name": "useWorkflow",
+      "file": "hooks/use-workflow.ts",
+      "purpose": "Load one workflow and save changes to its graph (saving is external tier, so the caller confirms first).",
+      "operations": [
+        "get_workflow_workflows__action_id__get",
+        "update_workflow_workflows__action_id__put"
+      ]
+    }
+  ],
+  "lib": [
+    {
+      "file": "lib/graph.ts",
+      "purpose": "Pure helpers: read a graph as ordered steps, add, move and remove steps while keeping connections and edges in sync, and the row types."
+    }
+  ],
+  "recipes": [
+    {
+      "file": "recipes/create-workflow.ts",
+      "title": "Create a workflow from a list of steps, validate it, and save it",
+      "when": "An automation is described; read the node catalog first, validate, then save (external)."
+    },
+    {
+      "file": "recipes/run-workflow-and-wait.ts",
+      "title": "Preview a workflow run, start it, and wait for the result",
+      "when": "A workflow should run now; plan is free, run is external, then poll the execution."
+    },
+    {
+      "file": "recipes/find-failed-runs.ts",
+      "title": "List a workflow's failed runs with their errors",
+      "when": "Something did not happen and the cause is needed; reading runs is free."
+    },
+    {
+      "file": "recipes/set-trigger.ts",
+      "title": "Change a workflow's trigger and skip the backlog",
+      "when": "A different start event or interval is wanted; external, and a cursor reset skips events."
+    }
+  ],
+  "prerequisites": [
+    {
+      "id": "workflow-resources",
+      "description": "Anything a step references (a list, a sequence, a mailbox, a form, a workbench) already exists; steps hold ids, not names.",
+      "where": "api",
+      "verify": "Run POST /workflows/validate on the graph: missing_references must be empty."
+    },
+    {
+      "id": "integrations",
+      "description": "Slack, Roam or LinkedIn steps need those integrations connected by a person in graph8.",
+      "where": "app",
+      "verify": "GET /workflows/integrations/slack/channels returns channels (or the equivalent for the provider)."
+    }
+  ],
+  "scopes": [
+    "workflows:delete",
+    "workflows:read",
+    "workflows:run"
+  ],
+  "defaults": [
+    {
+      "decision": "How a new workflow starts",
+      "default": "A manual trigger (trigger_type tool_call) and an end step; the person adds steps",
+      "askHuman": false
+    },
+    {
+      "decision": "Whether to enable a new workflow that sends messages",
+      "default": "Leave disabled until the person has seen the plan",
+      "askHuman": true
+    },
+    {
+      "decision": "Editing branching workflows",
+      "default": "Names and configs only; shape changes happen in the graph8 canvas",
+      "askHuman": false
+    },
+    {
+      "decision": "Run input",
+      "default": "Empty JSON object unless the workflow declares required inputs",
+      "askHuman": false
+    },
+    {
+      "decision": "Page size for run history",
+      "default": "25 rows",
+      "askHuman": false
+    }
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  }
+}

package/blocks/workflows/components/run-history.tsx

@@ -0,0 +1,136 @@
+"use client";
+
+/**
+ * RunHistory: a workflow's runs (or every run), one run's detail, and pause / resume / stop / restart.
+ *
+ * SDK operations, in the order the screen uses them:
+ *   1. listWorkflowExecutions  GET  /workflows/executions?action_id&status_filter&limit&offset  (read)
+ *   2. getExecution            GET  /workflows/executions/{execution_id}                       (read; polled while
+ *                              the run is pending or running, because the API has no stream)
+ *   3. pauseExecution          POST /workflows/executions/{id}/pause                           (external)
+ *   4. resumeExecution         POST /workflows/executions/{id}/resume                          (external)
+ *   5. stopExecution           POST /workflows/executions/{id}/stop                            (external)
+ *   6. restartExecution        POST /workflows/executions/{id}/restart                         (external)
+ *
+ * Every state-changing action goes through ConfirmSpendDialog: resuming or restarting a run can message people
+ * again. Statuses: pending | running | completed | failed | paused | pending_approval | stopped. `paused` and
+ * `pending_approval` wait for a person and are NOT terminal.
+ */
+
+import { useState } from "react";
+import { Button, Card, CardContent, CardHeader, CardTitle, Skeleton, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@graph8/sdk/ui";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useJobPoll } from "@/g8/hooks/use-job-poll";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { TERMINAL_STATUSES, WAITING_STATUSES, payload, str } from "../lib/graph";
+import type { ExecutionRow, Rec } from "../lib/graph";
+
+export interface RunHistoryProps {
+  /** Only this workflow's runs. Omit for every workflow. */
+  actionId?: string;
+  /** Open this run's detail first (for example the id returned by WorkflowList's onRunStarted). */
+  initialExecutionId?: string;
+  pageSize?: number;
+  className?: string;
+}
+
+type Verb = "pause" | "resume" | "stop" | "restart";
+const STATUSES = ["", "running", "completed", "failed", "paused", "pending_approval", "stopped"];
+const VERB_COPY: Record<Verb, { title: string; description: string; label: string }> = {
+  pause: { title: "Pause this run", description: "No further steps run until it is resumed.", label: "Pause" },
+  resume: { title: "Resume this run", description: "The remaining steps run now, including any that message people.", label: "Resume" },
+  stop: { title: "Stop this run", description: "The run ends and cannot be resumed.", label: "Stop" },
+  restart: { title: "Restart this run", description: "Runs the workflow again from the start with the same input. Steps that message people will run again.", label: "Restart" },
+};
+/** Which verbs make sense for a status. */
+const allowed = (status: string): Verb[] =>
+  status === "running" ? ["pause", "stop"] : status === "paused" || status === "pending_approval" ? ["resume", "stop"] : TERMINAL_STATUSES.includes(status) ? ["restart"] : [];
+
+function Detail({ executionId, onChanged }: { executionId: string; onChanged: () => void }) {
+  const [verb, setVerb] = useState<Verb | null>(null);
+  const poll = useJobPoll<Rec>(async (signal) => payload(await g8Get(`/workflows/executions/${encodeURIComponent(executionId)}`, undefined, { signal })), {
+    isTerminal: (e) => TERMINAL_STATUSES.includes(str(e.status)) || WAITING_STATUSES.includes(str(e.status)),
+  });
+  const act = useG8Mutation((v: Verb) => g8Post(`/workflows/executions/${encodeURIComponent(executionId)}/${v}`), {
+    onSuccess: () => { setVerb(null); poll.start(); onChanged(); },
+  });
+  const e = poll.status ?? {};
+  const status = str(e.status, "pending");
+  return (
+    <Card data-testid="run-detail">
+      <CardHeader><CardTitle className="text-sm">Run {executionId.slice(0, 8)}</CardTitle></CardHeader>
+      <CardContent className="space-y-3 text-sm">
+        {poll.error ? <ApiError error={poll.error} title="Could not read this run" onRetry={poll.start} /> : null}
+        {act.error ? <ApiError error={act.error} title="That action failed" /> : null}
+        <p>Status: <strong>{status.replace(/_/g, " ")}</strong>{e.duration_ms != null ? ` in ${Math.round(Number(e.duration_ms) / 100) / 10}s` : ""}</p>
+        {e.error_message ? <p className="text-destructive">{str(e.error_message)}</p> : null}
+        {e.input_data ? <details><summary>Input</summary><pre className="overflow-auto text-xs">{JSON.stringify(e.input_data, null, 2)}</pre></details> : null}
+        {e.output_data ? <details open><summary>Output</summary><pre className="overflow-auto text-xs">{JSON.stringify(e.output_data, null, 2)}</pre></details> : null}
+        <div className="flex gap-2">
+          {allowed(status).map((v) => <Button key={v} size="sm" variant="outline" onClick={() => setVerb(v)}>{VERB_COPY[v].label}</Button>)}
+        </div>
+        {verb ? (
+          <ConfirmSpendDialog open tier="external" title={VERB_COPY[verb].title} description={VERB_COPY[verb].description} confirmLabel={VERB_COPY[verb].label}
+            confirming={act.loading} onConfirm={() => void act.mutate(verb)} onCancel={() => setVerb(null)} />
+        ) : null}
+      </CardContent>
+    </Card>
+  );
+}
+
+export function RunHistory({ actionId, initialExecutionId, pageSize = 25, className }: RunHistoryProps) {
+  const [status, setStatus] = useState("");
+  const [offset, setOffset] = useState(0);
+  const [selected, setSelected] = useState<string | null>(initialExecutionId ?? null);
+  const list = useG8Query(
+    (signal) => g8Get("/workflows/executions", { action_id: actionId, status_filter: status || undefined, limit: pageSize, offset }, { signal }),
+    [actionId, status, offset, pageSize],
+  );
+  const body = payload(list.data);
+  const rows = (Array.isArray(body.executions) ? body.executions : []) as ExecutionRow[];
+  const total = typeof body.total_count === "number" ? body.total_count : rows.length;
+
+  return (
+    <div className={className}>
+      <div className="mb-3 flex items-center gap-2">
+        <select aria-label="Status" value={status} onChange={(e) => { setStatus(e.target.value); setOffset(0); }} className="border-input bg-background h-9 rounded-md border px-2 text-sm">
+          {STATUSES.map((s) => <option key={s} value={s}>{s ? s.replace(/_/g, " ") : "All statuses"}</option>)}
+        </select>
+        <Button size="sm" variant="outline" onClick={() => void list.refetch()}>Refresh</Button>
+      </div>
+      {list.error ? <ApiError error={list.error} onRetry={() => void list.refetch()} /> : null}
+      <div className="grid gap-4 lg:grid-cols-2">
+        <div>
+          {list.loading && !list.data ? <div className="space-y-2" aria-busy="true">{[0, 1, 2].map((i) => <Skeleton key={i} className="h-10 w-full" />)}</div> : !list.error && rows.length === 0 ? (
+            <EmptyState title="No runs yet" description="Runs appear here when a trigger fires or someone runs the workflow." />
+          ) : (
+            <Table>
+              <TableHeader><TableRow><TableHead>Started</TableHead><TableHead>Status</TableHead><TableHead>By</TableHead></TableRow></TableHeader>
+              <TableBody>
+                {rows.map((r) => (
+                  <TableRow key={r.execution_id} data-state={selected === r.execution_id ? "selected" : undefined}>
+                    <TableCell><button type="button" className="hover:underline" onClick={() => setSelected(r.execution_id)}>{new Date(str(r.started_at ?? r.created_at)).toLocaleString()}</button></TableCell>
+                    <TableCell className="capitalize">{r.status.replace(/_/g, " ")}</TableCell>
+                    <TableCell>{r.triggered_by ?? r.trigger_type ?? ""}</TableCell>
+                  </TableRow>
+                ))}
+              </TableBody>
+            </Table>
+          )}
+          <div className="mt-3 flex items-center justify-between text-sm">
+            <span className="text-muted-foreground">{total} {total === 1 ? "run" : "runs"}</span>
+            <div className="flex gap-2">
+              <Button size="sm" variant="outline" disabled={offset === 0} onClick={() => setOffset(Math.max(0, offset - pageSize))}>Previous</Button>
+              <Button size="sm" variant="outline" disabled={offset + pageSize >= total} onClick={() => setOffset(offset + pageSize)}>Next</Button>
+            </div>
+          </div>
+        </div>
+        <div>{selected ? <Detail key={selected} executionId={selected} onChanged={() => void list.refetch()} /> : <p className="text-muted-foreground text-sm">Select a run to see its input, output and errors.</p>}</div>
+      </div>
+    </div>
+  );
+}

package/blocks/workflows/components/trigger-config.tsx

@@ -0,0 +1,134 @@
+"use client";
+
+/**
+ * TriggerConfig: what starts a workflow (event type, polling interval, filters) and where its trigger cursor is.
+ *
+ * Event triggers read events newer than a stored cursor, so a workflow that was off for a week would replay a
+ * week of events when it comes back; "Reset cursor to now" skips that backlog.
+ *
+ * SDK operations, in the order the screen uses them:
+ *   1. getWorkflow         GET  /workflows/{id}                                   (read; via useWorkflow)
+ *   2. getTriggerStatus    GET  /workflows/{id}/trigger-status                    (read; type, interval, cursor)
+ *   3. getNodeTypesSchema  GET  /workflows/node-types/schema?node_type=trigger    (read; the trigger types offered)
+ *   4. updateWorkflow      PUT  /workflows/{id} { config }                        (external, via useWorkflow)
+ *   5. resetTriggerCursor  POST /workflows/{id}/trigger-reset                     (external: skips unprocessed events)
+ *
+ * Save and reset both go through ConfirmSpendDialog: a changed trigger decides what real events start real work.
+ */
+
+import { useState } from "react";
+import { Button, Card, CardContent, CardHeader, CardTitle, Input, Label, Skeleton, Textarea } from "@graph8/sdk/ui";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { useWorkflow } from "../hooks/use-workflow";
+import { asRec, nodeIdOf, nodesOf, payload, setStep, str, triggerOf } from "../lib/graph";
+import type { Rec } from "../lib/graph";
+
+export interface TriggerConfigProps {
+  actionId: string;
+  onSaved?: () => void;
+  className?: string;
+}
+
+/** The trigger config without the two fields that get their own inputs. */
+function restOf(config: Rec): string {
+  const { trigger_type: _t, polling_interval_minutes: _p, ...rest } = config;
+  return JSON.stringify(rest, null, 2);
+}
+
+type SaveHandle = ReturnType<typeof useWorkflow>["save"];
+
+function Form({ actionId, config, save, saveAndRefresh, trigger, types, onSaved }: { actionId: string; config: Rec; save: SaveHandle; saveAndRefresh: (u: { config: Rec }) => Promise<unknown>; trigger: Rec; types: string[]; onSaved: () => void }) {
+  const cfg = asRec(trigger.config);
+  const [type, setType] = useState(str(cfg.trigger_type));
+  const [interval, setIntervalMin] = useState(cfg.polling_interval_minutes == null ? "" : String(cfg.polling_interval_minutes));
+  const [rest, setRest] = useState(restOf(cfg));
+  const [confirm, setConfirm] = useState<"save" | "reset" | null>(null);
+  const reset = useG8Mutation(() => g8Post(`/workflows/${encodeURIComponent(actionId)}/trigger-reset`), { onSuccess: () => { setConfirm(null); onSaved(); } });
+  let parsed: Rec | null = null;
+  try { parsed = asRec(JSON.parse(rest || "{}")); } catch { parsed = null; }
+
+  const next = (): Rec => {
+    const merged: Rec = { ...parsed, trigger_type: type };
+    if (interval.trim()) merged.polling_interval_minutes = Number(interval);
+    return setStep(config, nodeIdOf(trigger), { config: merged });
+  };
+  const options = type && !types.includes(type) ? [type, ...types] : types;
+
+  return (
+    <Card>
+      <CardHeader><CardTitle className="text-sm">Trigger</CardTitle></CardHeader>
+      <CardContent className="space-y-3">
+        <div className="space-y-1">
+          <Label htmlFor="trg-type">Starts when</Label>
+          <select id="trg-type" value={type} onChange={(e) => setType(e.target.value)} className="border-input bg-background h-9 w-full rounded-md border px-2 text-sm">
+            {options.map((t) => <option key={t} value={t}>{t.replace(/_/g, " ")}</option>)}
+          </select>
+        </div>
+        <div className="space-y-1">
+          <Label htmlFor="trg-interval">Check every (minutes)</Label>
+          <Input id="trg-interval" type="number" min={1} value={interval} onChange={(e) => setIntervalMin(e.target.value)} className="w-32" />
+        </div>
+        <div className="space-y-1">
+          <Label htmlFor="trg-rest">Filters and other settings (JSON)</Label>
+          <Textarea id="trg-rest" rows={5} className="font-mono text-xs" value={rest} aria-invalid={parsed === null} onChange={(e) => setRest(e.target.value)} />
+          {parsed === null ? <p className="text-destructive text-xs">That is not valid JSON.</p> : null}
+        </div>
+        {save.error ? <ApiError error={save.error} title="Could not save the trigger" /> : null}
+        {reset.error ? <ApiError error={reset.error} title="Could not reset the cursor" /> : null}
+        <div className="flex gap-2">
+          <Button disabled={parsed === null || !type} onClick={() => setConfirm("save")}>Save trigger</Button>
+          <Button variant="outline" onClick={() => setConfirm("reset")}>Reset cursor to now</Button>
+        </div>
+      </CardContent>
+      {confirm ? (
+        <ConfirmSpendDialog open tier="external"
+          title={confirm === "save" ? "Save this trigger" : "Reset the trigger cursor to now"}
+          description={confirm === "save" ? "New events matching this trigger start runs that can reach real contacts." : "Events that arrived since the last run are skipped and never processed."}
+          confirmLabel={confirm === "save" ? "Save" : "Reset"} confirming={save.loading || reset.loading}
+          onConfirm={() => {
+            if (confirm === "reset") return void reset.mutate(undefined);
+            void saveAndRefresh({ config: next() }).then((r) => { setConfirm(null); if (r) onSaved(); });
+          }}
+          onCancel={() => setConfirm(null)} />
+      ) : null}
+    </Card>
+  );
+}
+
+export function TriggerConfig({ actionId, onSaved, className }: TriggerConfigProps) {
+  const wf = useWorkflow(actionId);
+  const status = useG8Query((signal) => g8Get(`/workflows/${encodeURIComponent(actionId)}/trigger-status`, undefined, { signal }), [actionId]);
+  const catalog = useG8Query((signal) => g8Get("/workflows/node-types/schema", { node_type: "trigger", detail: "slim" }, { signal }), []);
+
+  if (wf.loading) return <div className={className} aria-busy="true"><Skeleton className="h-40 w-full" /></div>;
+  if (wf.error) return <ApiError error={wf.error} onRetry={() => void wf.refetch()} />;
+  const trigger = triggerOf(wf.config);
+  const s = payload(status.data);
+  const entry = asRec(payload(catalog.data).node_type);
+  const types = Object.keys(asRec(entry.trigger_output_schemas)).sort();
+  const refresh = () => { void wf.refetch(); void status.refetch(); onSaved?.(); };
+
+  return (
+    <div className={className}>
+      <Card className="mb-4">
+        <CardHeader><CardTitle className="text-sm">Status</CardTitle></CardHeader>
+        <CardContent className="text-sm" data-testid="trigger-status">
+          {status.error ? <ApiError error={status.error} onRetry={() => void status.refetch()} /> : s.has_trigger === false || !trigger ? "This workflow has no trigger; it only runs when you run it." : (
+            <>
+              <p>{str(s.trigger_type).replace(/_/g, " ")}, checked every {str(s.polling_interval_minutes, "5")} minutes. {s.enabled === false ? "The workflow is disabled, so nothing fires." : "Enabled."}</p>
+              <p className="text-muted-foreground">Cursor: {s.cursor ? str(s.cursor) : "no events processed yet"}</p>
+            </>
+          )}
+        </CardContent>
+      </Card>
+      {catalog.error ? <p className="mb-2 text-xs">The trigger catalog could not be loaded; the current type is still editable.</p> : null}
+      {trigger ? <Form key={JSON.stringify(trigger.config)} actionId={actionId} config={wf.config} save={wf.save} saveAndRefresh={wf.saveAndRefresh} trigger={trigger} types={types} onSaved={refresh} /> : (
+        <p className="text-muted-foreground text-sm">There is no trigger node to configure ({nodesOf(wf.config).length} steps). Add a trigger step in the graph8 app.</p>
+      )}
+    </div>
+  );
+}

package/blocks/workflows/components/workflow-editor.tsx

@@ -0,0 +1,142 @@
+"use client";
+
+/**
+ * WorkflowEditor: a workflow as an ordered list of steps (not a canvas).
+ *
+ * Each step has a name and a JSON config. For a LINEAR workflow you can add a step (from the node catalog),
+ * move it up or down, or remove it; for a branching one only names and configs are editable, because a list
+ * cannot show where a branch goes (the graph8 app has the canvas). Saving rewrites `connections` and `edges`
+ * together (see ../lib/graph.ts) and PUTs the whole graph.
+ *
+ * SDK operations, in the order the screen uses them:
+ *   1. getWorkflow         GET /workflows/{id}                          (read; via useWorkflow)
+ *   2. getNodeTypesSchema  GET /workflows/node-types/schema?detail=slim (read; the "Add step" catalog)
+ *   3. updateWorkflow      PUT /workflows/{id} { config }               (external, via useWorkflow; saving can
+ *                          change what an enabled workflow sends, so it goes through ConfirmSpendDialog)
+ *
+ * Unsaved edits are kept in the page, never sent until the person confirms Save.
+ */
+
+import { useState } from "react";
+import { Button, Card, CardContent, CardHeader, CardTitle, Input, Skeleton, Textarea } from "@graph8/sdk/ui";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { useWorkflow } from "../hooks/use-workflow";
+import { addStep, asRec, canMove, isLinear, moveStep, newStep, nodeIdOf, nodeNameOf, nodeTypeOf, orderedSteps, payload, removeStep, setStep, str } from "../lib/graph";
+import type { Rec, WfNode } from "../lib/graph";
+
+export interface WorkflowEditorProps {
+  actionId: string;
+  onSaved?: () => void;
+  className?: string;
+}
+
+/** Types an author may add by hand. `start` is deprecated and `trigger` has its own screen (TriggerConfig). */
+const NOT_ADDABLE = new Set(["start", "trigger", "end"]);
+
+function StepCard({ step, index, canUp, canDown, linear, onChange, onMove, onRemove }: { step: WfNode; index: number; canUp: boolean; canDown: boolean; linear: boolean; onChange: (patch: Rec) => void; onMove: (d: -1 | 1) => void; onRemove: () => void }) {
+  const id = nodeIdOf(step);
+  const [text, setText] = useState(() => JSON.stringify(asRec(step.config), null, 2));
+  const [bad, setBad] = useState(false);
+  const canRemove = linear && nodeTypeOf(step) !== "trigger" && nodeTypeOf(step) !== "end";
+  return (
+    <Card data-testid={`step-${id}`}>
+      <CardHeader className="flex flex-row items-center gap-2">
+        <span className="text-muted-foreground text-xs">{index + 1}</span>
+        <CardTitle className="flex-1 text-sm">{nodeNameOf(step)} <span className="text-muted-foreground font-normal">({nodeTypeOf(step)})</span></CardTitle>
+        {linear ? (
+          <>
+            <Button size="sm" variant="ghost" aria-label={`Move ${id} up`} disabled={!canUp} onClick={() => onMove(-1)}>Up</Button>
+            <Button size="sm" variant="ghost" aria-label={`Move ${id} down`} disabled={!canDown} onClick={() => onMove(1)}>Down</Button>
+          </>
+        ) : null}
+        {canRemove ? <Button size="sm" variant="ghost" aria-label={`Remove ${id}`} onClick={onRemove}>Remove</Button> : null}
+      </CardHeader>
+      <CardContent className="space-y-2">
+        <Input aria-label={`Name of ${id}`} value={str(step.name)} onChange={(e) => onChange({ name: e.target.value })} />
+        <Textarea aria-label={`Config of ${id}`} rows={5} className="font-mono text-xs" value={text} aria-invalid={bad}
+          onChange={(e) => {
+            setText(e.target.value);
+            try { onChange({ config: JSON.parse(e.target.value) }); setBad(false); } catch { setBad(true); }
+          }} />
+        {bad ? <p className="text-destructive text-xs">Config must be valid JSON; the last valid version is kept.</p> : null}
+      </CardContent>
+    </Card>
+  );
+}
+
+function AddStep({ onAdd }: { onAdd: (type: string) => void }) {
+  const catalog = useG8Query((signal) => g8Get("/workflows/node-types/schema", { detail: "slim" }, { signal }), []);
+  const [type, setType] = useState("");
+  const types = (Array.isArray(payload(catalog.data).node_types) ? (payload(catalog.data).node_types as Rec[]) : [])
+    .filter((n) => !NOT_ADDABLE.has(str(n.node_type)) && n.deprecated !== true);
+  return (
+    <div className="flex items-center gap-2">
+      <select aria-label="Step type" value={type} onChange={(e) => setType(e.target.value)} className="border-input bg-background h-9 rounded-md border px-2 text-sm">
+        <option value="">{catalog.loading ? "Loading step types..." : "Choose a step type"}</option>
+        {types.map((n) => <option key={str(n.node_type)} value={str(n.node_type)}>{str(n.node_type).replace(/_/g, " ")}</option>)}
+      </select>
+      <Button variant="outline" disabled={!type} onClick={() => { onAdd(type); setType(""); }}>Add step</Button>
+      {catalog.error ? <span className="text-xs">The step catalog could not be loaded.</span> : null}
+    </div>
+  );
+}
+
+export function WorkflowEditor({ actionId, onSaved, className }: WorkflowEditorProps) {
+  const wf = useWorkflow(actionId);
+  // The draft remembers which workflow it belongs to, so switching `actionId` can never show or save the old one.
+  const [draftState, setDraftState] = useState<{ id: string; config: Rec } | null>(null);
+  const draft = draftState && draftState.id === actionId ? draftState.config : null;
+  const setDraft = (config: Rec | null) => setDraftState(config ? { id: actionId, config } : null);
+  const [confirm, setConfirm] = useState(false);
+  // Bumped on discard and after a save so StepCards re-read their config; typing never rewrites the textarea.
+  const [epoch, setEpoch] = useState(0);
+  const config = draft ?? wf.config;
+
+  if (wf.loading) return <div className={className} aria-busy="true"><Skeleton className="h-40 w-full" /></div>;
+  if (wf.error) return <ApiError error={wf.error} onRetry={() => void wf.refetch()} />;
+
+  const steps = orderedSteps(config);
+  const linear = isLinear(config);
+  const edit = (next: Rec) => setDraft(next);
+
+  return (
+    <div className={className}>
+      <div className="mb-4 flex flex-wrap items-center gap-2">
+        <h2 className="text-lg font-semibold">{str(wf.workflow.name, "Workflow")}</h2>
+        <span className="text-muted-foreground text-sm">{wf.workflow.enabled === false ? "Disabled" : "Enabled"}</span>
+        <div className="ml-auto flex items-center gap-2">
+          {draft ? <span className="text-sm">Unsaved changes</span> : null}
+          <Button variant="outline" disabled={!draft} onClick={() => { setDraft(null); setEpoch((e) => e + 1); }}>Discard</Button>
+          <Button disabled={!draft} onClick={() => setConfirm(true)}>Save workflow</Button>
+        </div>
+      </div>
+      {!linear ? <p className="text-muted-foreground mb-3 text-sm">This workflow branches, so steps can be renamed and reconfigured here but not added, moved or removed. Use the graph8 app to change its shape.</p> : null}
+      {wf.save.error ? <ApiError error={wf.save.error} title="Could not save the workflow" /> : null}
+      <div className="mb-4 space-y-3">
+        {steps.map((s, i) => (
+          <StepCard key={`${actionId}-${nodeIdOf(s)}-${epoch}`} step={s} index={i} canUp={linear && canMove(config, nodeIdOf(s), -1)} canDown={linear && canMove(config, nodeIdOf(s), 1)} linear={linear}
+            onChange={(patch) => edit(setStep(config, nodeIdOf(s), patch))}
+            onMove={(d) => edit(moveStep(config, nodeIdOf(s), d))}
+            onRemove={() => edit(removeStep(config, nodeIdOf(s)))} />
+        ))}
+      </div>
+      {linear ? (
+        <AddStep onAdd={(type) => {
+          const afterEnd = steps.length > 0 && nodeTypeOf(steps[steps.length - 1]) === "end";
+          const after = afterEnd ? (steps.length > 1 ? nodeIdOf(steps[steps.length - 2]) : null) : undefined;
+          edit(addStep(config, newStep(config, type, type.replace(/_/g, " ")), after));
+        }} />
+      ) : null}
+      {confirm ? (
+        <ConfirmSpendDialog open tier="external" title={`Save "${str(wf.workflow.name, "this workflow")}"`}
+          description={wf.workflow.enabled === false ? "The workflow is disabled, so saving does not start it." : "The workflow is enabled: new steps take effect on the next trigger and can reach real contacts."}
+          confirmLabel="Save" confirming={wf.save.loading}
+          onConfirm={() => void wf.saveAndRefresh({ config }).then((r) => { if (r) { setConfirm(false); setDraft(null); setEpoch((e) => e + 1); onSaved?.(); } else setConfirm(false); })}
+          onCancel={() => setConfirm(false)} />
+      ) : null}
+    </div>
+  );
+}