Workflow version history: list, diff on YAML and canvas, restore, and show the version a run used #431

Closed
opened 2026-10-27 13:36:18 +00:00 by sam · 0 comments
Owner

Purpose

Workflows now change often and from several places (canvas, YAML, restore shipped). An operator must be able to see how a workflow changed over time, who changed it, compare any two versions, and restore an earlier one, from the workflow itself.

Today

  • The control plane keeps every revision of a resource with actor, source and time: GET /api/control-plane/resources/{kind}/history (store method history(kind) in ui/src/stores/control-plane.ts) and per-field audit (/api/control-plane/audit).
  • All workflows live in one resource (workflow-definitions), so a revision is the whole collection; per-workflow history means filtering revisions to those where this workflow's entry changed.
  • Runs pin the definition digest they ran (task.WorkflowDefinitionDigest), so a run can be tied to the exact version it used.

Build

  1. A History tab beside Canvas/YAML/Performance/Runs: the revisions in which this workflow changed (added, edited, removed), newest first, with who, from where, when.
  2. Selecting a revision shows a readable diff against the current definition, both as YAML (line diff) and on the canvas (steps added, removed, changed highlighted).
  3. "Restore this version" puts that revision's YAML into the editor as unsaved changes (the operator saves deliberately).
  4. A run's version: in the run picker and run details, show which revision a run used (match by digest) and let the operator open it.

Context every agent needs

  • The Workflows page (ui/src/workflows/WorkflowsPage.vue, WorkflowEditor.vue) is archie-core's main operator surface: a Vue Flow canvas (WorkflowCanvas.vue, nodes in StepNode.vue, layout in workflow-graph.ts) that both edits a workflow definition and watches its runs. Edits are edits to the YAML document (workflow-edit.ts), so the canvas and the YAML tab never disagree. Read WORKFLOWS.md (repo root) for the workflow language.
  • The watched run comes from useWorkflowRuns (workflow-runs.ts): GET /api/tasks filtered by workflow, and GET /api/tasks/{id}/attempts for its recorded steps (stage rows: name, status ok|failed|interrupted|running, duration_ms, error). A step is recorded under its id, else its type. Live refresh is useLiveResource("tasks", ...) over the SSE stream.
  • Slide-in panels over the right edge of the canvas (StepEditor.vue, WorkflowSettings.vue) are the pattern for details and editing. Do not add a permanent side panel.
  • UI bar the maintainer has set (memory: canvas UI taste): direct manipulation (right-click menus, inline + points, panels that open on demand), no instructional filler text, the field that matters first, help text on hover, nothing that makes the page scroll when the canvas could pan. Drive every change in a headless browser (Playwright with the system Chrome works; stub /api/** with page.route) and look at screenshots at 1920x947 before calling it done.
  • AGENTS.md rules apply: cheapest change first, services own contracts (the dashboard reaches other services only through archie-ui's HTTP API and their gRPC contracts), no new binaries, regenerate and commit ui/dist with the change, task check gates the commit, tests only for the seams AGENTS.md lists.

Acceptance criteria

  • The History tab lists only revisions that changed this workflow, with actor, source and time.
  • Any revision can be diffed against the current definition as YAML and on the canvas.
  • Restore loads a revision as unsaved changes; nothing is written until Save.
  • A watched run shows the revision it ran. Uses the existing history endpoint (or the smallest addition). task check passes; screenshots reviewed.

Notes

Decision: forge safety is enforced by suppressing forge and push writes in a test run (recorded as forge_suppressed events on the step); forgerpc and worktreerpc also refuse a test run's credential.

Close reason

Closed


Imported from beads archie-core-t19m.9 · GitHub #1325 · type feature · priority P2 · created 2026-10-05 · closed 2026-10-13

## Purpose Workflows now change often and from several places (canvas, YAML, restore shipped). An operator must be able to see how a workflow changed over time, who changed it, compare any two versions, and restore an earlier one, from the workflow itself. ## Today - The control plane keeps every revision of a resource with actor, source and time: `GET /api/control-plane/resources/{kind}/history` (store method `history(kind)` in `ui/src/stores/control-plane.ts`) and per-field audit (`/api/control-plane/audit`). - All workflows live in one resource (`workflow-definitions`), so a revision is the whole collection; per-workflow history means filtering revisions to those where this workflow's entry changed. - Runs pin the definition digest they ran (`task.WorkflowDefinitionDigest`), so a run can be tied to the exact version it used. ## Build 1. A History tab beside Canvas/YAML/Performance/Runs: the revisions in which this workflow changed (added, edited, removed), newest first, with who, from where, when. 2. Selecting a revision shows a readable diff against the current definition, both as YAML (line diff) and on the canvas (steps added, removed, changed highlighted). 3. "Restore this version" puts that revision's YAML into the editor as unsaved changes (the operator saves deliberately). 4. A run's version: in the run picker and run details, show which revision a run used (match by digest) and let the operator open it. ## Context every agent needs - The Workflows page (`ui/src/workflows/WorkflowsPage.vue`, `WorkflowEditor.vue`) is archie-core's main operator surface: a Vue Flow canvas (`WorkflowCanvas.vue`, nodes in `StepNode.vue`, layout in `workflow-graph.ts`) that both edits a workflow definition and watches its runs. Edits are edits to the YAML document (`workflow-edit.ts`), so the canvas and the YAML tab never disagree. Read `WORKFLOWS.md` (repo root) for the workflow language. - The watched run comes from `useWorkflowRuns` (`workflow-runs.ts`): `GET /api/tasks` filtered by workflow, and `GET /api/tasks/{id}/attempts` for its recorded steps (stage rows: name, status ok|failed|interrupted|running, duration_ms, error). A step is recorded under its `id`, else its type. Live refresh is `useLiveResource("tasks", ...)` over the SSE stream. - Slide-in panels over the right edge of the canvas (`StepEditor.vue`, `WorkflowSettings.vue`) are the pattern for details and editing. Do not add a permanent side panel. - UI bar the maintainer has set (memory: canvas UI taste): direct manipulation (right-click menus, inline + points, panels that open on demand), no instructional filler text, the field that matters first, help text on hover, nothing that makes the page scroll when the canvas could pan. Drive every change in a headless browser (Playwright with the system Chrome works; stub `/api/**` with `page.route`) and look at screenshots at 1920x947 before calling it done. - AGENTS.md rules apply: cheapest change first, services own contracts (the dashboard reaches other services only through archie-ui's HTTP API and their gRPC contracts), no new binaries, regenerate and commit `ui/dist` with the change, `task check` gates the commit, tests only for the seams AGENTS.md lists. ### Acceptance criteria - The History tab lists only revisions that changed this workflow, with actor, source and time. - Any revision can be diffed against the current definition as YAML and on the canvas. - Restore loads a revision as unsaved changes; nothing is written until Save. - A watched run shows the revision it ran. Uses the existing history endpoint (or the smallest addition). `task check` passes; screenshots reviewed. ### Notes Decision: forge safety is enforced by suppressing forge and push writes in a test run (recorded as forge_suppressed events on the step); forgerpc and worktreerpc also refuse a test run's credential. ### Close reason Closed --- _Imported from beads `archie-core-t19m.9` · GitHub #1325 · type feature · priority P2 · created 2026-10-05 · closed 2026-10-13_
sam added the mediumfeature labels 2026-10-27 13:36:18 +00:00
sam self-assigned this 2026-10-27 13:36:18 +00:00
sam closed this issue 2026-10-27 13:36:18 +00:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: sam/archie#431