feat(workflow): orchestrate resumable dataflow handoffs

This commit is contained in:
2026-07-30 03:11:56 +02:00
parent a1654e70cf
commit a6e0e89829
18 changed files with 3938 additions and 27 deletions
+155
View File
@@ -84,6 +84,75 @@ export type WorkflowGovernance = {
automation_runtime_reason?: string | null;
};
export type WorkflowInstanceStatus =
| "running"
| "waiting"
| "completed"
| "failed"
| "cancelled";
export type WorkflowStepStatus =
| "running"
| "waiting"
| "completed"
| "failed"
| "cancelled"
| "superseded";
export type WorkflowInstanceStep = {
id: string;
sequence: number;
node_id: string;
node_type: string;
status: WorkflowStepStatus;
attempt: number;
input: Record<string, unknown>;
output: Record<string, unknown>;
handoff: Record<string, unknown>;
external_ref?: string | null;
started_at?: string | null;
finished_at?: string | null;
error?: string | null;
completed_by?: string | null;
created_at: string;
updated_at: string;
};
export type WorkflowInstanceEvent = {
id: string;
sequence: number;
step_id?: string | null;
kind: string;
actor_id?: string | null;
payload: Record<string, unknown>;
created_at: string;
};
export type WorkflowInstance = {
id: string;
definition_id: string;
definition_name: string;
definition_revision: number;
definition_hash: string;
status: WorkflowInstanceStatus;
idempotency_key: string;
correlation_id?: string | null;
current_step_id?: string | null;
input: Record<string, unknown>;
context: Record<string, unknown>;
output: Record<string, unknown>;
started_at: string;
finished_at?: string | null;
cancellation_requested_at?: string | null;
error?: string | null;
created_by?: string | null;
created_at: string;
updated_at: string;
steps: WorkflowInstanceStep[];
events: WorkflowInstanceEvent[];
replayed: boolean;
};
export type WorkflowDefinitionPayload = {
name: string;
description?: string | null;
@@ -232,3 +301,89 @@ export function workflowScopeReferenceProvider(
{ scope_type: scopeType }
);
}
export async function listWorkflowInstances(
settings: ApiSettings,
definitionId?: string | null
): Promise<WorkflowInstance[]> {
const params = new URLSearchParams();
if (definitionId) params.set("definition_id", definitionId);
const query = params.size ? `?${params.toString()}` : "";
const response = await apiFetch<{ instances: WorkflowInstance[] }>(
settings,
`/api/v1/workflow/instances${query}`
);
return response.instances;
}
export function startWorkflowInstance(
settings: ApiSettings,
definitionId: string,
payload: {
idempotency_key: string;
input?: Record<string, unknown>;
correlation_id?: string | null;
}
): Promise<WorkflowInstance> {
return apiFetch(
settings,
`/api/v1/workflow/definitions/${encodeURIComponent(definitionId)}/instances`,
{
method: "POST",
body: JSON.stringify(payload)
}
);
}
export function getWorkflowInstance(
settings: ApiSettings,
instanceId: string
): Promise<WorkflowInstance> {
return apiFetch(
settings,
`/api/v1/workflow/instances/${encodeURIComponent(instanceId)}`
);
}
export function reconcileWorkflowInstance(
settings: ApiSettings,
instanceId: string
): Promise<WorkflowInstance> {
return apiFetch(
settings,
`/api/v1/workflow/instances/${encodeURIComponent(instanceId)}/reconcile`,
{ method: "POST" }
);
}
export function resolveWorkflowStep(
settings: ApiSettings,
instanceId: string,
stepId: string,
payload: {
action: "complete" | "approve" | "changes" | "reject" | "resume" | "retry" | "cancel";
output?: Record<string, unknown>;
evidence?: string[];
comment?: string | null;
}
): Promise<WorkflowInstance> {
return apiFetch(
settings,
`/api/v1/workflow/instances/${encodeURIComponent(instanceId)}/steps/${encodeURIComponent(stepId)}/actions`,
{
method: "POST",
body: JSON.stringify(payload)
}
);
}
export function cancelWorkflowInstance(
settings: ApiSettings,
instanceId: string
): Promise<WorkflowInstance> {
return apiFetch(
settings,
`/api/v1/workflow/instances/${encodeURIComponent(instanceId)}/cancel`,
{ method: "POST" }
);
}
@@ -10,6 +10,7 @@ import {
CheckCircle2,
CopyPlus,
GitFork,
ListChecks,
Plus,
RefreshCw,
RotateCcw,
@@ -57,6 +58,7 @@ import WorkflowCanvas, {
updateWorkflowGraphNode
} from "./WorkflowCanvas";
import WorkflowInspector from "./WorkflowInspector";
import WorkflowRunsDialog from "./WorkflowRunsDialog";
import {
FALLBACK_WORKFLOW_LIBRARY,
draftFromDefinition,
@@ -103,6 +105,7 @@ export default function WorkflowPage({
const [deleteOpen, setDeleteOpen] = useState(false);
const [definitionSettingsOpen, setDefinitionSettingsOpen] = useState(false);
const [deriveOpen, setDeriveOpen] = useState(false);
const [runsOpen, setRunsOpen] = useState(false);
const canWrite = hasScope(auth, "workflow:definition:write")
|| hasScope(auth, "workflow:instance:admin");
@@ -114,6 +117,18 @@ export default function WorkflowPage({
&& canWrite
&& draft.governance?.actions.derive?.allowed
);
const canStart = Boolean(
draft?.id
&& (hasScope(auth, "workflow:instance:start")
|| hasScope(auth, "workflow:instance:admin"))
&& draft.governance?.actions.start?.allowed !== false
);
const canTransition = hasScope(auth, "workflow:instance:transition")
|| hasScope(auth, "workflow:instance:admin");
const selectedDefinition = useMemo(
() => definitions.find((item) => item.id === draft?.id) ?? null,
[definitions, draft?.id]
);
const dirty = Boolean(draft)
&& workflowFingerprint(draft) !== workflowFingerprint(savedDraft);
const displayedGraph = historicalRevision?.graph ?? draft?.graph ?? null;
@@ -531,6 +546,14 @@ export default function WorkflowPage({
<Button onClick={() => void validate()} disabled={working}>
<CheckCircle2 size={16} /> Validate
</Button>
{draft.id ? (
<Button
onClick={() => setRunsOpen(true)}
disabled={dirty || historicalRevision !== null}
>
<ListChecks size={16} /> Runs
</Button>
) : null}
<IconButton
label="Definition settings"
icon={<Settings2 size={16} />}
@@ -748,6 +771,14 @@ export default function WorkflowPage({
setSuccess("Created a pinned scoped copy.");
}}
/>
<WorkflowRunsDialog
open={runsOpen}
settings={settings}
definition={selectedDefinition}
canStart={canStart}
canTransition={canTransition}
onClose={() => setRunsOpen(false)}
/>
</main>
);
}
@@ -0,0 +1,516 @@
import {
useCallback,
useEffect,
useMemo,
useState
} from "react";
import {
ExternalLink,
Play,
RefreshCw,
RotateCcw,
XCircle
} from "lucide-react";
import {
Button,
ConfirmDialog,
Dialog,
DismissibleAlert,
FormField,
IconButton,
LoadingFrame,
StatusBadge,
type ApiSettings
} from "@govoplan/core-webui";
import {
cancelWorkflowInstance,
listWorkflowInstances,
reconcileWorkflowInstance,
resolveWorkflowStep,
startWorkflowInstance,
type WorkflowDefinition,
type WorkflowInstance,
type WorkflowInstanceStep
} from "../../api/workflow";
type WorkflowAction =
| "complete"
| "approve"
| "changes"
| "reject"
| "resume"
| "retry"
| "cancel";
export default function WorkflowRunsDialog({
open,
settings,
definition,
canStart,
canTransition,
onClose
}: {
open: boolean;
settings: ApiSettings;
definition: WorkflowDefinition | null;
canStart: boolean;
canTransition: boolean;
onClose: () => void;
}) {
const [instances, setInstances] = useState<WorkflowInstance[]>([]);
const [selectedId, setSelectedId] = useState<string | null>(null);
const [loading, setLoading] = useState(false);
const [working, setWorking] = useState(false);
const [error, setError] = useState("");
const [comment, setComment] = useState("");
const [evidence, setEvidence] = useState("");
const [cancelOpen, setCancelOpen] = useState(false);
const selected = useMemo(
() => instances.find((item) => item.id === selectedId) ?? instances[0] ?? null,
[instances, selectedId]
);
const currentStep = useMemo(
() => currentInstanceStep(selected),
[selected]
);
const allowedActions = useMemo(
() => handoffActions(currentStep),
[currentStep]
);
const mergeInstance = useCallback((instance: WorkflowInstance) => {
setInstances((current) => [
instance,
...current.filter((item) => item.id !== instance.id)
]);
setSelectedId(instance.id);
}, []);
const load = useCallback(async () => {
if (!open || !definition?.id) return;
setLoading(true);
setError("");
try {
const items = await listWorkflowInstances(settings, definition.id);
setInstances(items);
setSelectedId((current) => (
items.some((item) => item.id === current)
? current
: items[0]?.id ?? null
));
} catch (loadError) {
setError(errorMessage(loadError));
} finally {
setLoading(false);
}
}, [definition?.id, open, settings]);
useEffect(() => {
if (!open) return;
setComment("");
setEvidence("");
void load();
}, [load, open]);
useEffect(() => {
if (
!open
|| !canTransition
|| !selected
|| !currentStep
|| currentStep.node_type !== "workflow.dataflow"
|| !["queued", "retrying", "running"].includes(
String(currentStep.handoff.state ?? "")
)
) {
return;
}
let stopped = false;
const poll = window.setInterval(() => {
void reconcileWorkflowInstance(settings, selected.id)
.then((instance) => {
if (!stopped) mergeInstance(instance);
})
.catch((pollError) => {
if (!stopped) setError(errorMessage(pollError));
});
}, 2500);
return () => {
stopped = true;
window.clearInterval(poll);
};
}, [
canTransition,
currentStep,
mergeInstance,
open,
selected,
settings
]);
const start = async () => {
if (!definition?.id) return;
setWorking(true);
setError("");
try {
const instance = await startWorkflowInstance(settings, definition.id, {
idempotency_key: crypto.randomUUID(),
input: {}
});
mergeInstance(instance);
} catch (startError) {
setError(errorMessage(startError));
} finally {
setWorking(false);
}
};
const refreshSelected = async () => {
if (!selected) {
await load();
return;
}
setWorking(true);
setError("");
try {
const instance = canTransition
? await reconcileWorkflowInstance(settings, selected.id)
: (await listWorkflowInstances(settings, definition?.id))
.find((item) => item.id === selected.id);
if (instance) mergeInstance(instance);
else await load();
} catch (refreshError) {
setError(errorMessage(refreshError));
} finally {
setWorking(false);
}
};
const performAction = async (action: WorkflowAction) => {
if (!selected || !currentStep) return;
setWorking(true);
setError("");
try {
const instance = await resolveWorkflowStep(
settings,
selected.id,
currentStep.id,
{
action,
comment: comment.trim() || null,
evidence: evidence
.split("\n")
.map((item) => item.trim())
.filter(Boolean)
}
);
mergeInstance(instance);
setComment("");
setEvidence("");
} catch (actionError) {
setError(errorMessage(actionError));
} finally {
setWorking(false);
}
};
const cancel = async () => {
if (!selected) return;
setWorking(true);
setError("");
try {
mergeInstance(await cancelWorkflowInstance(settings, selected.id));
setCancelOpen(false);
} catch (cancelError) {
setError(errorMessage(cancelError));
} finally {
setWorking(false);
}
};
const actionUrl = typeof currentStep?.handoff.action_url === "string"
? currentStep.handoff.action_url
: "";
return (
<>
<Dialog
open={open}
title={`Runs${definition ? ` · ${definition.name}` : ""}`}
className="workflow-runs-dialog"
bodyClassName="workflow-runs-dialog-body"
onClose={onClose}
footer={<Button onClick={onClose}>Close</Button>}
>
<div className="workflow-runs-toolbar">
<span>
<strong>Workflow instances</strong>
<small>Revision-pinned runs and human handoffs</small>
</span>
<span>
<IconButton
label="Refresh runs"
icon={<RefreshCw size={16} />}
variant="ghost"
onClick={() => void refreshSelected()}
disabled={loading || working}
/>
<Button
variant="primary"
onClick={() => void start()}
disabled={!canStart || working || definition?.status !== "active"}
disabledReason={
definition?.status !== "active"
? "Activate a definition revision before starting it."
: undefined
}
>
<Play size={16} /> Start
</Button>
</span>
</div>
{error ? (
<DismissibleAlert tone="danger" resetKey={error}>
{error}
</DismissibleAlert>
) : null}
<LoadingFrame loading={loading} className="workflow-runs-frame">
<div className="workflow-runs-layout">
<div className="workflow-run-list">
{instances.map((instance) => (
<button
key={instance.id}
type="button"
className={instance.id === selected?.id ? "is-selected" : ""}
onClick={() => {
setSelectedId(instance.id);
setComment("");
setEvidence("");
}}
>
<span>
<strong>{formatDateTime(instance.started_at)}</strong>
<small>
Revision {instance.definition_revision} · {instance.steps.length} steps
</small>
</span>
<StatusBadge
status={instance.status}
label={instance.status}
/>
</button>
))}
{!instances.length ? (
<div className="workflow-run-empty">No runs yet</div>
) : null}
</div>
<div className="workflow-run-detail">
{selected ? (
<>
<header>
<span>
<strong>{selected.definition_name}</strong>
<small>
Revision {selected.definition_revision} · {selected.definition_hash.slice(0, 12)}
</small>
</span>
<span>
<StatusBadge status={selected.status} label={selected.status} />
{["running", "waiting"].includes(selected.status) ? (
<IconButton
label="Cancel workflow run"
icon={<XCircle size={16} />}
variant="danger"
onClick={() => setCancelOpen(true)}
disabled={!canTransition || working}
/>
) : null}
</span>
</header>
{selected.error ? (
<DismissibleAlert tone="danger" resetKey={selected.error}>
{selected.error}
</DismissibleAlert>
) : null}
{currentStep ? (
<section className="workflow-run-handoff">
<div>
<span>
<strong>
{String(
currentStep.handoff.title
?? currentStep.handoff.kind
?? currentStep.node_type
)}
</strong>
<small>
Step {currentStep.sequence} · attempt {currentStep.attempt}
</small>
</span>
<StatusBadge
status={String(currentStep.handoff.state ?? currentStep.status)}
label={String(currentStep.handoff.state ?? currentStep.status)}
/>
</div>
{typeof currentStep.handoff.message === "string" ? (
<p>{currentStep.handoff.message}</p>
) : null}
{typeof currentStep.handoff.instructions === "string"
&& currentStep.handoff.instructions ? (
<p>{currentStep.handoff.instructions}</p>
) : null}
{actionUrl ? (
<a href={actionUrl}>
Open linked Dataflow result <ExternalLink size={14} />
</a>
) : null}
{allowedActions.some((action) => action !== "cancel") ? (
<div className="workflow-run-action-form">
<FormField label="Comment">
<textarea
value={comment}
onChange={(event) => setComment(event.target.value)}
rows={2}
disabled={!canTransition || working}
/>
</FormField>
<FormField
label="Evidence references"
help="Enter one durable evidence reference per line."
>
<textarea
value={evidence}
onChange={(event) => setEvidence(event.target.value)}
rows={2}
disabled={!canTransition || working}
/>
</FormField>
<div className="workflow-run-actions">
{allowedActions
.filter((action) => action !== "cancel")
.map((action) => (
<Button
key={action}
variant={
action === "reject"
? "danger"
: action === "approve"
|| action === "complete"
|| action === "resume"
? "primary"
: undefined
}
onClick={() => void performAction(action)}
disabled={!canTransition || working}
>
{action === "retry" ? <RotateCcw size={15} /> : null}
{actionLabel(action)}
</Button>
))}
</div>
</div>
) : null}
</section>
) : null}
<section className="workflow-run-history">
<h3>Progress</h3>
<div>
{selected.steps.map((step) => (
<span key={step.id}>
<strong>{step.node_id}</strong>
<small>
{step.node_type} · attempt {step.attempt}
</small>
<StatusBadge status={step.status} label={step.status} />
</span>
))}
</div>
</section>
<section className="workflow-run-events">
<h3>Evidence trail</h3>
<div>
{[...selected.events].reverse().map((event) => (
<span key={event.id}>
<strong>{event.kind}</strong>
<small>
{formatDateTime(event.created_at)}
{event.actor_id ? ` · ${event.actor_id}` : ""}
</small>
</span>
))}
</div>
</section>
</>
) : (
<div className="workflow-run-empty">
Start a run to track its progress here.
</div>
)}
</div>
</div>
</LoadingFrame>
</Dialog>
<ConfirmDialog
open={cancelOpen}
title="Cancel workflow run"
message="Cancel this workflow instance and its active Dataflow run?"
confirmLabel="Cancel run"
tone="danger"
busy={working}
onCancel={() => setCancelOpen(false)}
onConfirm={() => void cancel()}
/>
</>
);
}
function currentInstanceStep(
instance: WorkflowInstance | null
): WorkflowInstanceStep | null {
if (!instance?.current_step_id) return null;
return instance.steps.find(
(step) => step.id === instance.current_step_id
) ?? null;
}
function handoffActions(step: WorkflowInstanceStep | null): WorkflowAction[] {
const actions = step?.handoff.allowed_actions;
if (!Array.isArray(actions)) return [];
return actions.filter((action): action is WorkflowAction => (
typeof action === "string"
&& [
"complete",
"approve",
"changes",
"reject",
"resume",
"retry",
"cancel"
].includes(action)
));
}
function actionLabel(action: WorkflowAction): string {
return {
complete: "Complete",
approve: "Approve",
changes: "Request changes",
reject: "Reject",
resume: "Resume",
retry: "Retry",
cancel: "Cancel"
}[action];
}
function formatDateTime(value: string): string {
return new Intl.DateTimeFormat(undefined, {
dateStyle: "medium",
timeStyle: "short"
}).format(new Date(value));
}
function errorMessage(error: unknown): string {
if (error instanceof Error) return error.message;
return "The Workflow request failed.";
}
+273
View File
@@ -656,6 +656,255 @@
padding: 7px 10px;
}
.workflow-runs-dialog {
width: min(1120px, calc(100vw - 32px));
height: min(760px, calc(100vh - 32px));
}
.workflow-runs-dialog-body {
display: flex;
min-height: 0;
flex-direction: column;
gap: 10px;
overflow: hidden;
padding: 0;
}
.workflow-runs-toolbar {
display: flex;
align-items: center;
justify-content: space-between;
gap: 12px;
flex: 0 0 auto;
min-height: 56px;
border-bottom: var(--border-line);
padding: 9px 12px;
}
.workflow-runs-toolbar > span {
display: flex;
align-items: center;
gap: 7px;
}
.workflow-runs-toolbar > span:first-child {
display: grid;
gap: 2px;
}
.workflow-runs-toolbar small {
color: var(--muted);
font-size: 11px;
}
.workflow-runs-frame,
.workflow-runs-layout,
.workflow-run-list,
.workflow-run-detail {
min-width: 0;
min-height: 0;
}
.workflow-runs-frame {
flex: 1 1 auto;
overflow: hidden;
}
.workflow-runs-layout {
display: grid;
grid-template-columns: minmax(240px, 300px) minmax(0, 1fr);
height: 100%;
overflow: hidden;
}
.workflow-run-list {
overflow: auto;
border-right: var(--border-line);
background: var(--panel-soft);
padding: 6px;
}
.workflow-run-list > button {
display: grid;
grid-template-columns: minmax(0, 1fr) auto;
align-items: center;
gap: 8px;
width: 100%;
min-height: 54px;
border: 0;
border-radius: var(--radius-sm);
background: transparent;
color: var(--text);
cursor: pointer;
padding: 8px 9px;
text-align: left;
}
.workflow-run-list > button:hover,
.workflow-run-list > button:focus-visible {
background: var(--primary-soft);
outline: none;
}
.workflow-run-list > button.is-selected {
background: var(--primary-soft-strong);
box-shadow: inset 3px 0 0 var(--accent);
}
.workflow-run-list strong,
.workflow-run-list small {
display: block;
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
}
.workflow-run-list strong {
color: var(--text-strong);
font-size: 12px;
}
.workflow-run-list small {
margin-top: 4px;
color: var(--muted);
font-size: 10px;
}
.workflow-run-detail {
display: flex;
flex-direction: column;
overflow: auto;
}
.workflow-run-detail > header,
.workflow-run-handoff > div:first-child {
display: flex;
align-items: center;
justify-content: space-between;
gap: 10px;
}
.workflow-run-detail > header {
position: sticky;
z-index: 2;
top: 0;
min-height: 56px;
border-bottom: var(--border-line);
background: var(--panel);
padding: 9px 12px;
}
.workflow-run-detail > header > span {
display: flex;
align-items: center;
gap: 7px;
}
.workflow-run-detail > header > span:first-child {
display: grid;
min-width: 0;
gap: 2px;
}
.workflow-run-detail > header strong,
.workflow-run-detail > header small {
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
}
.workflow-run-detail > header small {
color: var(--muted);
font-size: 10px;
}
.workflow-run-handoff,
.workflow-run-history,
.workflow-run-events {
display: grid;
gap: 10px;
border-bottom: var(--border-line);
padding: 12px;
}
.workflow-run-handoff p {
margin: 0;
color: var(--muted);
font-size: 12px;
line-height: 1.45;
}
.workflow-run-handoff a {
display: inline-flex;
align-items: center;
gap: 5px;
width: fit-content;
color: var(--accent);
font-size: 12px;
}
.workflow-run-action-form {
display: grid;
grid-template-columns: repeat(2, minmax(0, 1fr));
gap: 10px;
}
.workflow-run-action-form textarea {
width: 100%;
resize: vertical;
}
.workflow-run-actions {
display: flex;
grid-column: 1 / -1;
flex-wrap: wrap;
gap: 7px;
}
.workflow-run-actions .btn {
display: inline-flex;
align-items: center;
gap: 5px;
}
.workflow-run-history h3,
.workflow-run-events h3 {
margin: 0;
color: var(--text-strong);
font-size: 12px;
}
.workflow-run-history > div,
.workflow-run-events > div {
display: grid;
}
.workflow-run-history > div > span,
.workflow-run-events > div > span {
display: grid;
grid-template-columns: minmax(0, 1fr) minmax(160px, auto) auto;
align-items: center;
gap: 9px;
min-height: 38px;
border-top: var(--border-line);
padding: 6px 2px;
}
.workflow-run-history small,
.workflow-run-events small {
color: var(--muted);
font-size: 10px;
}
.workflow-run-empty {
display: grid;
min-height: 120px;
place-items: center;
color: var(--muted);
font-size: 12px;
text-align: center;
}
@media (max-width: 1180px) {
.workflow-shell {
grid-template-columns: 240px minmax(0, 1fr);
@@ -749,4 +998,28 @@
.workflow-palette-items button {
min-width: 128px;
}
.workflow-runs-layout {
grid-template-columns: 1fr;
grid-template-rows: minmax(120px, 28%) minmax(0, 1fr);
}
.workflow-run-list {
border-right: 0;
border-bottom: var(--border-line);
}
.workflow-run-action-form {
grid-template-columns: 1fr;
}
.workflow-run-history > div > span,
.workflow-run-events > div > span {
grid-template-columns: minmax(0, 1fr) auto;
}
.workflow-run-history > div > span small,
.workflow-run-events > div > span small {
grid-column: 1 / -1;
}
}