create-safest-tools 0.2.0

package/template/console/workflows/WorkflowStudio.tsx

@@ -0,0 +1,331 @@
+import { useEffect, useMemo, useRef, useState, useSyncExternalStore, type FormEvent } from "react";
+import { readable } from "../lib/format";
+import { ApiRequestError, errorMessage, mutationHeaders, requestJson } from "../lib/http";
+import { getShellSnapshot, subscribeToShell } from "../shell/store";
+import { announceWorkflowChanged, workflowEvents } from "./events";
+import { insertWorkflowNode, removeWorkflowNode, workflowNodeChoices } from "./graph";
+import { WorkflowCanvas } from "./WorkflowCanvas";
+import type {
+  JsonObject,
+  QueueListItem,
+  QueueListResponse,
+  StudioConsoleState,
+  WorkflowAuthorityMode,
+  WorkflowDetail,
+  WorkflowGraph,
+  WorkflowNode,
+  WorkflowPinResponse,
+  WorkflowPublishResponse,
+  WorkflowResponse,
+  WorkflowSaveResponse,
+  WorkflowTestResponse,
+  WorkflowValidationResponse,
+  WorkflowVersionResponse,
+} from "./types";
+
+function jsonObject(value: string, label: string): JsonObject {
+  const parsed: unknown = JSON.parse(value || "{}");
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`${label} must be a JSON object.`);
+  return parsed as JsonObject;
+}
+
+function errorResponse<T>(cause: unknown, status: number): T | null {
+  if (!(cause instanceof ApiRequestError) || cause.status !== status || !cause.body || typeof cause.body !== "object") return null;
+  return cause.body as T;
+}
+
+function validationState(workflow: WorkflowDetail, heading: string): StudioConsoleState {
+  return workflow.draft?.validation
+    ? { kind: "validation", heading, validation: workflow.draft.validation }
+    : { kind: "message", heading: "Published workflow", detail: "This immutable version can be inspected or pinned to a queue." };
+}
+
+function WorkflowConsole({ state }: { state: StudioConsoleState }) {
+  if (state.kind === "validation") {
+    const issues = [...(state.validation.errors || []).map((issue) => ({ ...issue, tone: "Error" })), ...(state.validation.warnings || []).map((issue) => ({ ...issue, tone: "Warning" }))];
+    return <>
+      <p>{state.heading}: {state.validation.valid ? "ready" : "needs changes"}. {state.validation.errors?.length || 0} errors and {state.validation.warnings?.length || 0} warnings.</p>
+      {issues.map((issue, index) => <div className="console-issue" key={`${issue.code}-${issue.nodeId || issue.edgeId || issue.path || index}`}><strong>{issue.tone}</strong><span>{issue.message}</span><code>{issue.nodeId || issue.edgeId || issue.path || issue.code}</code></div>)}
+      {state.validation.valid && !state.validation.warnings?.length ? <p>No blocking problems. Estimated maximum: {state.validation.estimatedMaximumSteps ?? "—"} steps.</p> : null}
+    </>;
+  }
+  if (state.kind === "test") {
+    const terminal = state.result.result?.terminalCode || state.result.result?.terminal_code || "—";
+    return <><p>Fixture {state.fixtureName}: {readable(state.result.status)}. Terminal {terminal}.</p>{(state.result.result?.steps || []).map((step, index) => <div className="console-issue" key={`${step.nodeId || step.node_id || "step"}-${index}`}><strong>Step</strong><span>{step.nodeId || step.node_id || "Step"}</span><code>{readable(step.state || "completed")}</code></div>)}</>;
+  }
+  return <><p><strong>{state.heading}</strong></p><p>{state.detail}</p></>;
+}
+
+function NodeInspector({ node, readOnly, busy, onApply, onRemove }: {
+  node: WorkflowNode | null;
+  readOnly: boolean;
+  busy: boolean;
+  onApply: (node: WorkflowNode) => Promise<void>;
+  onRemove: (node: WorkflowNode) => Promise<void>;
+}) {
+  const [name, setName] = useState("");
+  const [description, setDescription] = useState("");
+  const [errorPort, setErrorPort] = useState("");
+  const [mapping, setMapping] = useState("{}");
+  const [config, setConfig] = useState("{}");
+  const [error, setError] = useState("");
+
+  useEffect(() => {
+    setName(node?.name || ""); setDescription(node?.description || ""); setErrorPort(node?.error_port || "");
+    setMapping(JSON.stringify(node?.input_mapping || {}, null, 2)); setConfig(JSON.stringify(node?.config || {}, null, 2)); setError("");
+  }, [node?.id, node?.name, node?.description, node?.error_port, node?.input_mapping, node?.config]);
+
+  if (!node) return <div className="node-inspector-empty"><h3>Select a step</h3><p>Review its inputs, retries, and failure path.</p></div>;
+  const submit = async (event: FormEvent<HTMLFormElement>): Promise<void> => {
+    event.preventDefault(); setError("");
+    try {
+      await onApply({
+        ...node,
+        name: name.trim(),
+        ...(description.trim() ? { description: description.trim() } : { description: undefined }),
+        ...(errorPort.trim() ? { error_port: errorPort.trim() } : { error_port: undefined }),
+        input_mapping: jsonObject(mapping, "Input mapping"),
+        config: jsonObject(config, "Configuration"),
+      });
+    } catch (cause) { setError(errorMessage(cause, "The step configuration is not valid JSON.")); }
+  };
+  const removable = node.kind !== "start" && node.kind !== "end";
+  return <form onSubmit={(event) => void submit(event)}>
+    <p className="context-label">{readable(node.kind)}</p><h3>{node.name}</h3>
+    <label>Name<input maxLength={160} required disabled={readOnly || busy} value={name} onChange={(event) => setName(event.currentTarget.value)} /></label>
+    <label>Description<textarea maxLength={2000} disabled={readOnly || busy} value={description} onChange={(event) => setDescription(event.currentTarget.value)} /></label>
+    <label>Failure port<input maxLength={100} disabled={readOnly || busy} value={errorPort} onChange={(event) => setErrorPort(event.currentTarget.value)} placeholder="operations" /></label>
+    <label>Input mapping <small>Only mapped data leaves the workflow context.</small><textarea className="code-input" spellCheck={false} disabled={readOnly || busy} value={mapping} onChange={(event) => setMapping(event.currentTarget.value)} /></label>
+    <label>Configuration <small>JSON settings for this step type.</small><textarea className="code-input" spellCheck={false} disabled={readOnly || busy} value={config} onChange={(event) => setConfig(event.currentTarget.value)} /></label>
+    <p className="error" role="alert">{error}</p>
+    {!readOnly ? <div className="inspector-actions">{removable ? <button className="danger-button" type="button" disabled={busy} onClick={() => void onRemove(node)}>Remove step</button> : <span /> }<button className="primary" type="submit" disabled={busy}>{busy ? "Saving…" : "Apply"}</button></div> : null}
+  </form>;
+}
+
+export function WorkflowStudio() {
+  const shell = useSyncExternalStore(subscribeToShell, getShellSnapshot, getShellSnapshot);
+  const dialogRef = useRef<HTMLDialogElement>(null);
+  const closeRef = useRef<HTMLButtonElement>(null);
+  const [workflowId, setWorkflowId] = useState<string | null>(null);
+  const [openWarning, setOpenWarning] = useState("");
+  const [workflow, setWorkflow] = useState<WorkflowDetail | null>(null);
+  const [graph, setGraph] = useState<WorkflowGraph | null>(null);
+  const [selectedNodeId, setSelectedNodeId] = useState<string | null>(null);
+  const [queues, setQueues] = useState<QueueListItem[]>([]);
+  const [authorityMode, setAuthorityMode] = useState<WorkflowAuthorityMode>("assist");
+  const [loading, setLoading] = useState(false);
+  const [saving, setSaving] = useState(false);
+  const [action, setAction] = useState<"" | "validate" | "test" | "publish" | "pin">("");
+  const [error, setError] = useState("");
+  const [advanced, setAdvanced] = useState(false);
+  const [graphJson, setGraphJson] = useState("");
+  const [consoleState, setConsoleState] = useState<StudioConsoleState>({ kind: "message", heading: "Workflow studio", detail: "Open a draft to validate and test it." });
+  const [pinOpen, setPinOpen] = useState(false);
+  const [pinQueueId, setPinQueueId] = useState("");
+  const [pinMode, setPinMode] = useState<"primary" | "shadow">("primary");
+  const canPublish = shell.session?.permissions.publishWorkflows === true;
+  const canPin = shell.session?.permissions.manageWorkflowPins === true;
+  const readOnly = Boolean(workflow && !workflow.draft);
+  const busy = loading || saving || Boolean(action);
+  const selectedNode = useMemo(() => graph?.nodes.find((node) => node.id === selectedNodeId) ?? null, [graph, selectedNodeId]);
+
+  const clear = (): void => {
+    setWorkflowId(null); setOpenWarning(""); setWorkflow(null); setGraph(null); setSelectedNodeId(null); setQueues([]); setLoading(false); setSaving(false); setAction(""); setError(""); setAdvanced(false); setGraphJson(""); setPinOpen(false);
+  };
+  const close = (): void => { if (!busy) clear(); };
+
+  useEffect(() => {
+    const openStudio = (event: Event): void => {
+      if (!(event instanceof CustomEvent) || typeof event.detail?.workflowId !== "string") return;
+      setOpenWarning(typeof event.detail.warning === "string" ? event.detail.warning : "");
+      setWorkflowId(event.detail.workflowId);
+    };
+    window.addEventListener(workflowEvents.openStudio, openStudio);
+    return () => window.removeEventListener(workflowEvents.openStudio, openStudio);
+  }, []);
+  useEffect(() => {
+    const dialog = dialogRef.current;
+    if (!dialog) return;
+    if (workflowId && !dialog.open) { dialog.showModal(); requestAnimationFrame(() => closeRef.current?.focus()); }
+    if (!workflowId && dialog.open) dialog.close();
+  }, [workflowId]);
+  useEffect(() => {
+    if (workflowId && shell.currentView !== "workflows" && !busy) clear();
+  }, [shell.currentView, workflowId, busy]);
+  useEffect(() => {
+    if (!workflowId) return;
+    let active = true;
+    const load = async (): Promise<void> => {
+      setLoading(true); setError(""); setWorkflow(null); setGraph(null); setAdvanced(false); setPinOpen(false);
+      try {
+        const [response, queueResponse] = await Promise.all([
+          requestJson<WorkflowResponse>(`/v1/admin/workflows/${encodeURIComponent(workflowId)}`),
+          requestJson<QueueListResponse>("/v1/admin/queues").catch(() => ({ queues: [] })),
+        ]);
+        if (!active) return;
+        const detail = response.workflow;
+        let nextGraph = detail.draft?.graph ?? null;
+        if (!nextGraph && detail.activeVersionId) {
+          const published = await requestJson<WorkflowVersionResponse>(`/v1/admin/workflows/${encodeURIComponent(workflowId)}/versions/${encodeURIComponent(detail.activeVersionId)}`);
+          if (!active) return;
+          nextGraph = published.version.graph;
+        }
+        if (!nextGraph) throw new Error("This workflow has no draft or published graph to open.");
+        const availableQueues = (queueResponse.queues || []).filter((queue) => queue.status === "active");
+        setWorkflow(detail); setGraph(structuredClone(nextGraph)); setGraphJson(JSON.stringify(nextGraph, null, 2));
+        setSelectedNodeId(nextGraph.entry_node_id || nextGraph.nodes[0]?.id || null); setQueues(availableQueues);
+        setPinQueueId(availableQueues[0]?.id || ""); setAuthorityMode(detail.activeVersion?.authorityMode || "assist");
+        setConsoleState(openWarning ? { kind: "message", heading: "Workflow created with a warning", detail: openWarning } : validationState(detail, "Stored validation"));
+      } catch (cause) { if (active) setError(errorMessage(cause, "The workflow could not be opened.")); }
+      finally { if (active) setLoading(false); }
+    };
+    void load();
+    return () => { active = false; };
+  }, [workflowId, openWarning]);
+
+  const saveGraph = async (nextGraph: WorkflowGraph): Promise<boolean> => {
+    if (!workflowId || !workflow?.draft || readOnly) return false;
+    setSaving(true); setError("");
+    try {
+      const result = await requestJson<WorkflowSaveResponse>(`/v1/admin/workflows/${encodeURIComponent(workflowId)}/draft`, {
+        method: "PUT", headers: { "content-type": "application/json" }, body: JSON.stringify({ expected_revision: workflow.draft.revision, graph: nextGraph }),
+      });
+      setGraph(structuredClone(nextGraph)); setGraphJson(JSON.stringify(nextGraph, null, 2));
+      setWorkflow((current) => current?.draft ? { ...current, draft: { ...current.draft, revision: result.revision, graphDigest: result.graphDigest, graph: structuredClone(nextGraph), validation: result.validation, validationStatus: result.validation.valid ? "valid" : "invalid" } } : current);
+      setConsoleState({ kind: "validation", heading: "Draft saved and checked", validation: result.validation });
+      announceWorkflowChanged();
+      return true;
+    } catch (cause) { setError(errorMessage(cause, "The workflow draft could not be saved.")); return false; }
+    finally { setSaving(false); }
+  };
+
+  const fetchValidation = async (): Promise<WorkflowValidationResponse | null> => {
+    if (!workflowId) return null;
+    try {
+      return await requestJson<WorkflowValidationResponse>(`/v1/admin/workflows/${encodeURIComponent(workflowId)}/validate`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ authority_mode: authorityMode }) });
+    } catch (cause) {
+      const invalid = errorResponse<WorkflowValidationResponse>(cause, 422);
+      if (invalid?.validation) return invalid;
+      throw cause;
+    }
+  };
+  const fetchTest = async (): Promise<{ fixtureName: string; result: WorkflowTestResponse } | null> => {
+    if (!workflowId) return null;
+    const fixture = workflow?.fixtures?.[0];
+    if (!fixture) throw new Error("Add a server-recorded fixture before publishing this workflow.");
+    try {
+      const result = await requestJson<WorkflowTestResponse>(`/v1/admin/workflows/${encodeURIComponent(workflowId)}/test`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ fixture_id: fixture.id }) });
+      return { fixtureName: fixture.name, result };
+    } catch (cause) {
+      const failed = errorResponse<WorkflowTestResponse>(cause, 422);
+      if (failed?.status) return { fixtureName: fixture.name, result: failed };
+      throw cause;
+    }
+  };
+  const validate = async (): Promise<void> => {
+    setAction("validate"); setError("");
+    try {
+      const result = await fetchValidation();
+      if (result) {
+        setWorkflow((current) => current?.draft ? { ...current, draft: { ...current.draft, validation: result.validation, validationStatus: result.validation.valid ? "valid" : "invalid" } } : current);
+        setConsoleState({ kind: "validation", heading: "Validation result", validation: result.validation });
+      }
+    }
+    catch (cause) { setError(errorMessage(cause, "Validation failed.")); }
+    finally { setAction(""); }
+  };
+  const test = async (): Promise<void> => {
+    setAction("test"); setError("");
+    try { const result = await fetchTest(); if (result) setConsoleState({ kind: "test", ...result }); }
+    catch (cause) { setError(errorMessage(cause, "The fixture test failed.")); }
+    finally { setAction(""); }
+  };
+  const publish = async (): Promise<void> => {
+    if (!workflowId || !workflow?.draft || !canPublish) return;
+    setAction("publish"); setError("");
+    try {
+      const validation = await fetchValidation();
+      if (!validation) return;
+      setConsoleState({ kind: "validation", heading: "Publication check", validation: validation.validation });
+      if (!validation.validation.valid) return;
+      const tested = await fetchTest();
+      if (!tested) return;
+      setConsoleState({ kind: "test", ...tested });
+      if (tested.result.status !== "passed") return;
+      if (!window.confirm("Publish this exact tested draft as an immutable workflow version? Existing runs will not change.")) return;
+      const result = await requestJson<WorkflowPublishResponse>(`/v1/admin/workflows/${encodeURIComponent(workflowId)}/publish`, {
+        method: "POST", headers: mutationHeaders(), body: JSON.stringify({ expected_revision: workflow.draft.revision, authority_mode: authorityMode, test_evidence: { test_run_id: tested.result.testRunId } }),
+      });
+      setWorkflow((current) => current ? { ...current, activeVersionId: result.versionId, activeVersion: { id: result.versionId, version: result.version, authorityMode, publishedAt: new Date().toISOString(), bundleDigest: result.bundleDigest } } : current);
+      setConsoleState({ kind: "message", heading: `Published version ${result.version}`, detail: `Bundle ${result.bundleDigest}. Pin this version to a queue when you are ready to use it.` });
+      setPinOpen(true); announceWorkflowChanged();
+    } catch (cause) { setError(errorMessage(cause, "The workflow could not be published.")); }
+    finally { setAction(""); }
+  };
+  const pin = async (event: FormEvent<HTMLFormElement>): Promise<void> => {
+    event.preventDefault();
+    if (!workflow?.activeVersionId || !pinQueueId || !canPin) return;
+    setAction("pin"); setError("");
+    try {
+      await requestJson<WorkflowPinResponse>(`/v1/admin/queues/${encodeURIComponent(pinQueueId)}/workflow-pin`, { method: "PUT", headers: mutationHeaders(), body: JSON.stringify({ workflow_version_id: workflow.activeVersionId, mode: pinMode }) });
+      const queue = queues.find((candidate) => candidate.id === pinQueueId);
+      setConsoleState({ kind: "pin", heading: "Workflow pinned", detail: `${workflow.name} is now the ${pinMode} workflow for ${queue?.name || "the selected queue"}. New eligible reports use it; active runs do not change.` });
+      setPinOpen(false); announceWorkflowChanged();
+    } catch (cause) { setError(errorMessage(cause, "The workflow could not be pinned.")); }
+    finally { setAction(""); }
+  };
+  const applyNode = async (node: WorkflowNode): Promise<void> => {
+    if (!graph) return;
+    const next = structuredClone(graph);
+    next.nodes = next.nodes.map((candidate) => candidate.id === node.id ? node : candidate);
+    await saveGraph(next);
+  };
+  const removeNode = async (node: WorkflowNode): Promise<void> => {
+    if (!graph || !window.confirm(`Remove “${node.name}” and reconnect its surrounding steps?`)) return;
+    const next = removeWorkflowNode(graph, node.id);
+    if (await saveGraph(next)) setSelectedNodeId(next.entry_node_id || next.nodes[0]?.id || null);
+  };
+  const addNode = async (kind: WorkflowNode["kind"], name: string): Promise<void> => {
+    if (!graph) return;
+    const inserted = insertWorkflowNode(graph, kind, name, queues[0]?.id);
+    if (await saveGraph(inserted.graph)) setSelectedNodeId(inserted.nodeId);
+  };
+  const applyGraphJson = async (): Promise<void> => {
+    setError("");
+    try {
+      const parsed: unknown = JSON.parse(graphJson);
+      if (!parsed || typeof parsed !== "object" || !Array.isArray((parsed as WorkflowGraph).nodes) || !Array.isArray((parsed as WorkflowGraph).edges)) throw new Error("The workflow graph must contain node and edge lists.");
+      const next = parsed as WorkflowGraph;
+      if (await saveGraph(next)) setSelectedNodeId(next.entry_node_id || next.nodes[0]?.id || null);
+    } catch (cause) { setError(errorMessage(cause, "The graph JSON is invalid.")); }
+  };
+
+  const subtitle = workflow?.draft
+    ? `${workflow.activeVersion ? `Published v${workflow.activeVersion.version} · ` : ""}Draft revision ${workflow.draft.revision}`
+    : workflow?.activeVersion ? `Published v${workflow.activeVersion.version} · read-only contract` : "Loading workflow…";
+  return (
+    <dialog ref={dialogRef} className="studio-dialog workflow-studio-dialog" aria-labelledby="workflow-studio-title" onCancel={(event) => { event.preventDefault(); close(); }} data-react-slice="workflow-studio">
+      <div className="studio-toolbar">
+        <div><button ref={closeRef} className="icon-button" type="button" aria-label="Close workflow studio" disabled={busy} onClick={close}>←</button><div><h2 id="workflow-studio-title">{workflow?.name || (loading ? "Loading workflow…" : "Workflow studio")}</h2><small>{subtitle}</small></div></div>
+        <div className="studio-actions">
+          <label className="studio-authority">Authority<select value={authorityMode} disabled={busy || readOnly} onChange={(event) => setAuthorityMode(event.currentTarget.value as WorkflowAuthorityMode)}><option value="off">Off</option><option value="shadow">Shadow</option><option value="assist">Assist</option><option value="bounded_auto">Bounded auto</option></select></label>
+          <span className="save-state">{saving ? "Saving…" : workflow?.draft ? "All changes saved" : "Read-only"}</span>
+          <button className="secondary" type="button" disabled={busy || readOnly || !workflow} onClick={() => void validate()}>{action === "validate" ? "Checking…" : "Check"}</button>
+          <button className="secondary" type="button" disabled={busy || readOnly || !workflow} onClick={() => void test()}>{action === "test" ? "Testing…" : "Test"}</button>
+          {canPublish ? <button className="primary" type="button" disabled={busy || readOnly || !workflow} onClick={() => void publish()}>{action === "publish" ? "Publishing…" : "Publish"}</button> : null}
+          {canPin ? <button className="secondary" type="button" disabled={busy || !workflow?.activeVersionId} onClick={() => setPinOpen((value) => !value)}>Pin to queue</button> : null}
+        </div>
+      </div>
+      {loading ? <div className="workflow-studio-loading"><div className="skeleton-block" role="status" aria-label="Loading workflow studio" /></div> : graph && workflow ? <>
+        <div className="studio-body">
+          <aside className="node-palette"><h3>Add a step</h3><p>Choose a step. Use Advanced graph for branches or parallel paths.</p><div className="node-palette-list">{workflowNodeChoices.map((choice) => <button className="palette-button" type="button" disabled={busy || readOnly} onClick={() => void addNode(choice.kind, choice.name)} key={choice.kind}><i className={choice.tone} /><span><strong>{choice.name}</strong><small>{choice.detail}</small></span></button>)}</div><button className="text-button" type="button" disabled={busy} onClick={() => { setAdvanced((value) => !value); setGraphJson(JSON.stringify(graph, null, 2)); }}>{advanced ? "Hide advanced graph" : "Advanced graph JSON"}</button></aside>
+          <main className="workflow-canvas-shell"><div className="canvas-legend"><span><i />Read-only</span><span><i className="human" />Human</span><span><i className="action" />Action</span></div><WorkflowCanvas graph={graph} selectedNodeId={selectedNodeId} onSelect={setSelectedNodeId} /></main>
+          <aside className="node-inspector"><NodeInspector node={selectedNode} readOnly={readOnly} busy={busy} onApply={applyNode} onRemove={removeNode} /></aside>
+        </div>
+        {advanced ? <section className="graph-json-editor"><div><h3>Advanced graph JSON</h3><p>Edit branches, parallel groups, and typed mappings.</p></div><textarea aria-label="Workflow graph JSON" spellCheck={false} readOnly={readOnly || busy} value={graphJson} onChange={(event) => setGraphJson(event.currentTarget.value)} />{!readOnly ? <button className="secondary" type="button" disabled={busy} onClick={() => void applyGraphJson()}>Apply JSON</button> : null}</section> : null}
+      </> : null}
+      <section className="studio-console" aria-label="Checks and test results"><div className="console-head"><strong>Checks and test results</strong><span>{workflow?.draft?.validationStatus ? readable(workflow.draft.validationStatus) : readOnly ? "Published" : "Not checked"}</span></div><div className="console-output"><WorkflowConsole state={consoleState} />{pinOpen ? <form className="pin-control" onSubmit={(event) => void pin(event)}><label>Queue<select required disabled={busy} value={pinQueueId} onChange={(event) => setPinQueueId(event.currentTarget.value)}><option value="">Select a queue</option>{queues.map((queue) => <option value={queue.id} key={queue.id}>{queue.name}</option>)}</select></label><label>Mode<select disabled={busy} value={pinMode} onChange={(event) => setPinMode(event.currentTarget.value as "primary" | "shadow")}><option value="primary">Primary</option><option value="shadow">Shadow</option></select></label><button className="primary" type="submit" disabled={busy || !pinQueueId}>{action === "pin" ? "Pinning…" : "Pin published version"}</button></form> : null}</div></section>
+      <p className="error studio-error" role="alert">{error}</p>
+    </dialog>
+  );
+}

package/template/console/workflows/WorkflowWorkspace.tsx

@@ -0,0 +1,82 @@
+import { useCallback, useEffect, useState, useSyncExternalStore } from "react";
+import { PageHeader } from "../components/PageHeader";
+import { readable } from "../lib/format";
+import { errorMessage, requestJson } from "../lib/http";
+import { getShellSnapshot, subscribeToShell } from "../shell/store";
+import { openWorkflowCreate, openWorkflowStudio, workflowEvents } from "./events";
+import type { WorkflowListResponse, WorkflowSummary } from "./types";
+
+function WorkflowCard({ workflow }: { workflow: WorkflowSummary }) {
+  const version = workflow.activeVersion?.version;
+  const authority = workflow.activeVersion?.authorityMode;
+  return (
+    <article className="object-card workflow-card">
+      <div className="object-card-head">
+        <span className="object-icon" aria-hidden="true">⌘</span>
+        <span className={`badge${workflow.status !== "active" ? " urgent" : ""}`}>{version ? `v${version}` : "Draft"}</span>
+      </div>
+      <h3>{workflow.name}</h3>
+      <p>{workflow.description || "No description yet."}</p>
+      <div className="object-card-meta">
+        <div><span>Purpose</span><strong>{readable(workflow.purpose)}</strong></div>
+        <div><span>Authority</span><strong>{readable(authority || "Not published")}</strong></div>
+        <div><span>Queue pins</span><strong>{workflow.activePinCount || 0}</strong></div>
+      </div>
+      <div className="object-card-footer">
+        <small>{workflow.draft ? `Draft revision ${workflow.draft.revision}` : "Published contract"}</small>
+        <button className="secondary" type="button" onClick={() => openWorkflowStudio(workflow.id)}>Open studio</button>
+      </div>
+    </article>
+  );
+}
+
+export function WorkflowWorkspace() {
+  const shell = useSyncExternalStore(subscribeToShell, getShellSnapshot, getShellSnapshot);
+  const canManage = shell.session?.permissions.manageWorkflows === true;
+  const [workflows, setWorkflows] = useState<WorkflowSummary[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [refreshing, setRefreshing] = useState(false);
+  const [error, setError] = useState("");
+
+  const load = useCallback(async (refresh = false): Promise<void> => {
+    if (!canManage) { setWorkflows([]); setLoading(false); return; }
+    if (refresh) setRefreshing(true); else setLoading(true);
+    setError("");
+    try {
+      const response = await requestJson<WorkflowListResponse>("/v1/admin/workflows");
+      setWorkflows(Array.isArray(response.workflows) ? response.workflows : []);
+    } catch (cause) {
+      setError(errorMessage(cause, "Workflows could not be loaded."));
+    } finally {
+      setLoading(false);
+      setRefreshing(false);
+    }
+  }, [canManage]);
+
+  useEffect(() => {
+    if (shell.currentView === "workflows") void load();
+  }, [shell.currentView, shell.session?.actor.id, load]);
+  useEffect(() => {
+    const changed = (): void => { if (shell.currentView === "workflows") void load(true); };
+    window.addEventListener(workflowEvents.changed, changed);
+    return () => window.removeEventListener(workflowEvents.changed, changed);
+  }, [shell.currentView, load]);
+
+  return (
+    <div className="page-stack" data-react-slice="workflow-workspace">
+      <PageHeader titleId="workflows-title" title="Workflows" description="Build and publish the path each report follows.">
+        <div className="surface-buttons">
+          <button className="secondary" type="button" disabled={loading || refreshing || !canManage} onClick={() => void load(true)}>{refreshing ? "Refreshing…" : "Refresh"}</button>
+          <button className="primary" type="button" disabled={!canManage} onClick={openWorkflowCreate}>New workflow</button>
+        </div>
+      </PageHeader>
+      <div className="safety-boundary"><strong>Read-only steps inspect data. Actions change it.</strong><span>Publishing checks every failure path.</span></div>
+      <div className="object-grid workflow-list" aria-busy={loading || refreshing}>
+        {loading ? <><div className="skeleton-card" /><div className="skeleton-card" /></> : workflows.length ? workflows.map((workflow) => <WorkflowCard workflow={workflow} key={workflow.id} />) : error ? null : (
+          <div className="empty-product"><span aria-hidden="true">⌘</span><h2>No workflows yet</h2><p>Start with human review and add automation when you need it.</p>{canManage ? <button className="primary" type="button" onClick={openWorkflowCreate}>New workflow</button> : null}</div>
+        )}
+      </div>
+      <p className="error surface-error" role="alert">{error}</p>
+    </div>
+  );
+}

package/template/console/workflows/events.ts

@@ -0,0 +1,17 @@
+export const workflowEvents = {
+  openCreate: "safest:workflows:create-open",
+  openStudio: "safest:workflows:studio-open",
+  changed: "safest:workflows:changed",
+} as const;
+
+export function openWorkflowCreate(): void {
+  window.dispatchEvent(new Event(workflowEvents.openCreate));
+}
+
+export function openWorkflowStudio(workflowId: string, warning = ""): void {
+  window.dispatchEvent(new CustomEvent(workflowEvents.openStudio, { detail: { workflowId, warning } }));
+}
+
+export function announceWorkflowChanged(): void {
+  window.dispatchEvent(new Event(workflowEvents.changed));
+}

package/template/console/workflows/graph.ts

@@ -0,0 +1,156 @@
+import { readable } from "../lib/format";
+import type { JsonObject, WorkflowEdge, WorkflowGraph, WorkflowNode, WorkflowNodeKind } from "./types";
+
+export interface NodePosition { x: number; y: number }
+export interface EdgeGeometry { kind: "forward" | "reverse" | "vertical"; start: NodePosition; end: NodePosition }
+
+export const workflowNodeChoices: Array<{ kind: WorkflowNodeKind; name: string; detail: string; tone: string }> = [
+  { kind: "enrichment", name: "Enrichment", detail: "Read-only component", tone: "" },
+  { kind: "parallel_group", name: "Parallel group", detail: "Run independent branches", tone: "" },
+  { kind: "join", name: "Join", detail: "Required and optional results", tone: "" },
+  { kind: "condition", name: "Condition", detail: "Deterministic branch", tone: "" },
+  { kind: "ai_proposal", name: "AI proposal", detail: "Bounded structured suggestion", tone: "ai" },
+  { kind: "human_task", name: "Human task", detail: "Durable person-in-loop wait", tone: "human" },
+  { kind: "send_message", name: "Send message", detail: "Audience-safe communication", tone: "human" },
+  { kind: "wait_for_event", name: "Wait for reply", detail: "Resume from an external event", tone: "human" },
+  { kind: "decision", name: "Decision", detail: "Immutable policy outcome", tone: "human" },
+  { kind: "action", name: "Action", detail: "Approved customer-side effect", tone: "action" },
+];
+
+export function nodeVisualClass(kind: WorkflowNodeKind): string {
+  if (kind === "human_task" || kind === "wait_for_event" || kind === "send_message" || kind === "decision") return "human";
+  if (kind === "action") return "action";
+  if (kind === "ai_proposal") return "ai";
+  return "";
+}
+
+export function nodePosition(node: Pick<WorkflowNode, "metadata">, index: number): NodePosition {
+  const x = Number(node.metadata?.x);
+  const y = Number(node.metadata?.y);
+  return { x: Number.isFinite(x) ? x : 35 + (index % 5) * 205, y: Number.isFinite(y) ? y : 70 + Math.floor(index / 5) * 125 };
+}
+
+export function canvasSize(graph: WorkflowGraph): { width: number; height: number; positions: Map<string, NodePosition> } {
+  const positions = new Map(graph.nodes.map((node, index) => [node.id, nodePosition(node, index)]));
+  return {
+    width: Math.max(920, ...[...positions.values()].map((position) => position.x + 200)),
+    height: Math.max(580, ...[...positions.values()].map((position) => position.y + 158)),
+    positions,
+  };
+}
+
+export function workflowEdgeGeometry(from: NodePosition, to: NodePosition, lane = 0): EdgeGeometry {
+  const nodeWidth = 168;
+  const nodeHeight = 78;
+  const targetClearance = 8;
+  const horizontalGap = to.x - (from.x + nodeWidth);
+  const laneOffset = lane * 9;
+  if (horizontalGap >= 0) return {
+    kind: "forward",
+    start: { x: from.x + nodeWidth, y: from.y + nodeHeight / 2 + laneOffset },
+    end: { x: to.x - targetClearance, y: to.y + nodeHeight / 2 + laneOffset },
+  };
+  const reverseGap = from.x - (to.x + nodeWidth);
+  if (reverseGap >= 0) return {
+    kind: "reverse",
+    start: { x: from.x, y: from.y + nodeHeight / 2 + laneOffset },
+    end: { x: to.x + nodeWidth + targetClearance, y: to.y + nodeHeight / 2 + laneOffset },
+  };
+  const goingDown = to.y >= from.y;
+  return {
+    kind: "vertical",
+    start: { x: from.x + nodeWidth / 2 + laneOffset, y: goingDown ? from.y + nodeHeight : from.y },
+    end: { x: to.x + nodeWidth / 2 + laneOffset, y: goingDown ? to.y - targetClearance : to.y + nodeHeight + targetClearance },
+  };
+}
+
+export function workflowEdgePath(geometry: EdgeGeometry, lane = 0): string {
+  const { start, end } = geometry;
+  if (geometry.kind === "forward") {
+    const bend = Math.max(28, Math.abs(end.x - start.x) * .42);
+    return `M ${start.x} ${start.y} C ${start.x + bend} ${start.y}, ${end.x - bend} ${end.y}, ${end.x} ${end.y}`;
+  }
+  if (geometry.kind === "reverse") {
+    const routeY = Math.min(start.y, end.y) - 42 - Math.abs(lane) * 12;
+    return `M ${start.x} ${start.y} C ${start.x - 34} ${start.y}, ${start.x - 34} ${routeY}, ${start.x - 68} ${routeY} L ${end.x + 68} ${routeY} C ${end.x + 34} ${routeY}, ${end.x + 34} ${end.y}, ${end.x} ${end.y}`;
+  }
+  const bend = Math.max(28, Math.abs(end.y - start.y) * .38);
+  const direction = end.y >= start.y ? 1 : -1;
+  return `M ${start.x} ${start.y} C ${start.x} ${start.y + bend * direction}, ${end.x} ${end.y - bend * direction}, ${end.x} ${end.y}`;
+}
+
+export function workflowEdgeLabel(edge: WorkflowEdge): string {
+  if (edge.label) return edge.label;
+  return ["success", "input", "completed", "recorded", "sent", "handed_off", "applied", "started", "received"].includes(edge.from.port) ? "" : readable(edge.from.port);
+}
+
+export function workflowEdgeTone(edge: WorkflowEdge): "standard" | "warning" | "exception" {
+  if (/error|failed|rejected|timeout/u.test(edge.from.port)) return "exception";
+  if (/uncertain|cancelled|expired/u.test(edge.from.port)) return "warning";
+  return "standard";
+}
+
+function defaultNodeConfig(kind: WorkflowNodeKind, queueId?: string): JsonObject {
+  if (kind === "human_task") return { queue_id: queueId || "select-a-queue", response_schema: { type: "object" } };
+  if (kind === "enrichment") return { component_version_id: "select-a-published-component-version" };
+  if (kind === "action") return { component_version_id: "select-a-published-action-version", approval_mode: "human" };
+  if (kind === "ai_proposal") return { model_alias_version_id: "select-a-model-alias-version", result_ports: ["proposed", "uncertain"] };
+  if (kind === "send_message") return { audience: "reporter", template_version_id: "select-a-template-version" };
+  if (kind === "wait_for_event") return { event_type: "reporter.reply" };
+  if (kind === "decision") return { policy_version_id: "select-a-policy-version" };
+  if (kind === "condition") return { cases: [], default_port: "default" };
+  if (kind === "join") return { required_ports: ["required"], optional_ports: [] };
+  if (kind === "parallel_group") return { branch_ids: [] };
+  return {};
+}
+
+function outputPort(kind: WorkflowNodeKind): string {
+  if (kind === "action") return "applied";
+  if (kind === "decision") return "recorded";
+  if (kind === "human_task") return "completed";
+  if (kind === "send_message") return "sent";
+  return "success";
+}
+
+export function insertWorkflowNode(graph: WorkflowGraph, kind: WorkflowNodeKind, name: string, queueId?: string): { graph: WorkflowGraph; nodeId: string } {
+  const next = structuredClone(graph);
+  const idBase = kind.replaceAll("_", "-");
+  let nodeId = idBase;
+  let suffix = 2;
+  while (next.nodes.some((node) => node.id === nodeId)) nodeId = `${idBase}-${suffix++}`;
+  const end = next.nodes.find((node) => node.kind === "end");
+  const index = end ? Math.max(1, next.nodes.indexOf(end)) : next.nodes.length;
+  next.nodes.splice(index, 0, {
+    id: nodeId,
+    kind,
+    name,
+    description: "",
+    input_mapping: {},
+    config: defaultNodeConfig(kind, queueId),
+    metadata: nodePosition({ metadata: undefined }, index),
+  });
+  const incoming = end ? next.edges.find((edge) => edge.to.node_id === end.id) : undefined;
+  if (incoming && end) {
+    incoming.to = { node_id: nodeId, port: "input" };
+    next.edges.push({ id: `edge-${nodeId}-${end.id}`.slice(0, 100), from: { node_id: nodeId, port: outputPort(kind) }, to: { node_id: end.id, port: "input" } });
+  }
+  return { graph: next, nodeId };
+}
+
+export function removeWorkflowNode(graph: WorkflowGraph, nodeId: string): WorkflowGraph {
+  const next = structuredClone(graph);
+  const node = next.nodes.find((candidate) => candidate.id === nodeId);
+  if (!node || node.kind === "start" || node.kind === "end") return next;
+  const incoming = next.edges.filter((edge) => edge.to.node_id === nodeId);
+  const outgoing = next.edges.filter((edge) => edge.from.node_id === nodeId);
+  next.nodes = next.nodes.filter((candidate) => candidate.id !== nodeId);
+  next.edges = next.edges.filter((edge) => edge.from.node_id !== nodeId && edge.to.node_id !== nodeId);
+  for (const before of incoming) for (const after of outgoing) {
+    next.edges.push({
+      id: `edge-${before.from.node_id.slice(0, 30)}-${after.to.node_id.slice(0, 30)}-${crypto.randomUUID().slice(0, 6)}`,
+      from: before.from,
+      to: after.to,
+    });
+  }
+  return next;
+}