Skip to content

feat(workflows): update a saved workflow from a finished run - #27663

Closed
weijian722 wants to merge 1 commit into
kirodotdev:mainfrom
weijian722:feat/workflow-update-from-run
Closed

weijian722 wants to merge 1 commit into
kirodotdev:mainfrom
weijian722:feat/workflow-update-from-run

Conversation

@weijian722

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: The dashboard owner can append a finished workflow run's script to a saved workflow as that workflow's next revision, instead of only saving it as a new copy.

A finished run's Save workflow button always creates a new library entry. When someone edits a saved workflow's script in chat, runs it, and saves it under the same slug, they get <slug>-2 instead of revision N+1. The only way to add a revision today is to paste the whole script into Customize → Workflows. The workflow.update change card from #25708 can't help with larger scripts: it caps a script at 10,000 bytes and refuses non-ASCII outside comments.

This PR adds the backend half. The Update button and dialog come in a follow-up PR for the same issue.

Why it matters

Iterating on a saved workflow in chat (run it, ask for a change, run again) is the normal way people build one. Without an update path, the library either fills with -2/-3 copies whose /workflow commands nobody remembers, or the owner hand-pastes scripts and can paste the wrong file. Both leave the saved copy out of step with the one actually tested.

Not a goal

  • The dashboard button and dialog: a separate PR for the same issue.
  • Any MCP tool. Agents still cannot write the library (RFC §6.7, test_workflow_library_mutations_are_human_only).
  • Changing what POST /api/workflows/runs/{run_id}/promote returns.

What changed (motivation → approach → change)

A run whose script you edited and tested can now become the next revision of the saved workflow it came from, so the library keeps one workflow with its history instead of a new <slug>-2 copy each time. This PR adds the two routes the coming Update dialog will call:

Route (owner-only) What it does
GET /api/workflows/runs/{run_id}/update-definition?workflow= Names the saved workflow an update would revise (id, slug, name, revision, format) and returns the diff from its current source to the run's. Without workflow it suggests one, or returns null.
POST /api/workflows/runs/{run_id}/update-definition {workflow, expected_revision} Appends the run's exact source as that workflow's next revision.

The update reuses what promotion already trusts. The run must pass promote's checks: an ad-hoc run (not a saved invocation), finished or a paused TaskRunner plan, still holding its original source. Those checks are now one helper, _reusable_run, which both paths call. The library's own expected_revision lock still catches a stale writer. Two refusals are new: a run whose format differs from the workflow's, and a source identical to the pinned revision, which would otherwise append an empty revision. Every refusal has its own code (404, 409 or 400). The service half is in src/kiro_crew/workflows/service.py. The routes are in src/kiro_crew/dashboard/handlers/workflows.py, registered in src/kiro_crew/dashboard/server_runtime/mcp_routes.py, behind the same owner gates as promote and audited in SEL.

The preview suggests a target, in order: the run's derived_from, the script's META["adapted_from"], the slug of its META name, then the slug of the run's name. An edited rerun of a saved Python workflow now keeps that workflow as derived_from, as an adapted TaskRunner plan already does (passed through src/kiro_crew/workflows/runner.py and registry.py). Without it the most common case, editing a saved workflow and rerunning it, fell through to the META name and could suggest a same-named copy. Its diff is workflow_source_diff in src/kiro_crew/dashboard/change_cards_readers.py: the change card's diff without WORKFLOW_DIFF_MAX, because this diff is never stored in a card. It also spells out hidden characters on every line, since a run's script never went through the card's character checks. On a card the new script already passed those checks, so card diffs are unchanged. docs/system-specs/modules/workflows.md documents both routes and the update rules.

Backwards compatibility

Compatible: two new routes and one new service method. Promotion keeps the same checks, refusals and responses, and a card diff renders exactly as before. An edited Python rerun's snapshot now carries a derived_from it used to leave null; Python promotion still takes lineage only from META["adapted_from"].

Removes nothing: no route, field, key or behaviour is removed or narrowed.

Tests

  • test/test_workflows_service_update_from_run.py (new; test_workflows_service.py is at its line cap):
    • an update appends the run's raw source and keeps every earlier revision;
    • a stale revision, an unchanged source, a format mismatch, a missing workflow and a missing run are each refused with nothing written;
    • a saved invocation is refused by both the update and the preview;
    • the preview suggests a target from the META name, adapted_from and a TaskRunner run's derived_from, and an explicit workflow wins;
    • an edited rerun of a saved workflow with a custom slug is suggested back to that workflow over a same-named decoy, and a further rerun carries the ancestry forward. With the derived_from hand-off removed, this test fails.
  • test/test_workflow_definition_handlers.py: the preview returns only the target summary plus the diff; each refusal maps to its status and code; workflow and an integer expected_revision are required; app-token and anonymous callers get 403, with their SEL rows.
  • test/test_r7_owner_gate_positive_controls.py / test_r7_owner_gate_refusals.py: the owner reaches both routes; a non-owner gets owner_only on both, and nothing runs.
  • Contract pins updated for the new routes: the MCP route table, the lazy-import inventory, and the request-body cap register.
  • Breaking the unchanged-source guard turns test_update_run_definition_refuses_without_writing red.
  • Determinism: the 13 new tests ran 20× at -n0 and 10× at -n 4 --dist loadgroup --max-worker-restart=2 beside test_workflows_service.py and test_change_card_workflow_save.py, then in a shuffled order (seed 25822). All green.

Manual verification

N/A for this PR: unit tests cover both routes end to end through aiohttp. The click-through path (run, edit, Update, revision N → N+1) is verified in the follow-up PR that adds the dialog.

Related Issues

Part of #27525

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

I contribute this under the project's Apache-2.0 license.

@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention labels Nov 2, 2026
@weijian722
weijian722 marked this pull request as ready for review November 2, 2026 04:02
@weijian722
weijian722 requested review from a team and KiroCrewCaptain as code owners November 2, 2026 04:02
@weijian722
weijian722 requested a review from buluoray November 2, 2026 04:02
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 2, 2026
A finished ad-hoc run could only be promoted into a new definition, so
saving an edited script under an existing slug produced `<slug>-2`
instead of a new revision. The only way to append one was pasting the
script into Customize -> Workflows.

Add an owner-only `POST /api/workflows/runs/{run_id}/update-definition`
that appends the run's exact source as a chosen definition's next
revision, pinned by `expected_revision`. The run passes promotion's
checks (now shared as `_reusable_run`), must match the definition's
format, and an unchanged source is refused. Its `GET` preview suggests
the target from the run's lineage or the script's META name and returns
an uncapped diff, `workflow_source_diff`, split out of the change
card's capped `_workflow_diff`.

An edited rerun of a saved Python workflow now keeps that workflow as
`derived_from` ancestry, as an adapted TaskRunner plan already does, so
the preview suggests the workflow it came from.

Part of kirodotdev#27525
@weijian722
weijian722 force-pushed the feat/workflow-update-from-run branch from 3ce8c2a to d8b420f Compare November 2, 2026 20:11
@github-actions github-actions Bot added merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 2, 2026
@bolichen97

Copy link
Copy Markdown
Contributor

[operator: bolichen97] Continuing this in #32352; thanks for the start.

bolichen97 added a commit that referenced this pull request Nov 7, 2026
A finished ad-hoc run could only be promoted into a new definition, so
saving an edited script under an existing slug produced `<slug>-2`
instead of a new revision. The only way to append one was pasting the
script into Customize -> Workflows.

Add an owner-only `POST /api/workflows/runs/{run_id}/update-definition`
that appends the run's exact source as a chosen definition's next
revision, pinned by `expected_revision` and by the run source's SHA-256
its `GET` preview returned, so a paused plan replanned while the owner
reads the diff is refused rather than saved unseen. The run passes
promotion's checks (now shared as `_reusable_run`), must match the
definition's format, and an unchanged source is refused. The preview
suggests the target from the run's lineage or the script's META name
and returns an uncapped diff, `workflow_source_diff`, split out of the
change card's capped `_workflow_diff`. The logic lives in the new
`workflows/update_from_run.py`, below the service in the workflows
layering contract: it is handed the service and never imports it, so
the `META.adapted_from` parser both need moves to `library.py`.

An edited rerun of a saved Python workflow keeps that workflow as
`derived_from` ancestry, as an adapted TaskRunner plan already does, so
the preview suggests the workflow it came from.

Builds on #27663.

Part of #27525
bolichen97 added a commit that referenced this pull request Nov 7, 2026
A finished ad-hoc run could only be promoted into a new definition, so
saving an edited script under an existing slug produced `<slug>-2`
instead of a new revision. The only way to append one was pasting the
script into Customize -> Workflows.

Add an owner-only `POST /api/workflows/runs/{run_id}/update-definition`
that appends the run's exact source as a chosen definition's next
revision, pinned by `expected_revision` and by the run source's SHA-256
its `GET` preview returned, so a paused plan replanned while the owner
reads the diff is refused rather than saved unseen. The run passes
promotion's checks (now shared as `_reusable_run`), must match the
definition's format, and an unchanged source is refused. The preview
suggests the target from the run's lineage or the script's META name
and returns an uncapped diff, `workflow_source_diff`, split out of the
change card's capped `_workflow_diff`. The logic lives in the new
`workflows/update_from_run.py`, below the service in the workflows
layering contract: it is handed the service and never imports it, so
the `META.adapted_from` parser both need moves to `library.py`.

An edited rerun of a saved Python workflow keeps that workflow as
`derived_from` ancestry, as an adapted TaskRunner plan already does, so
the preview suggests the workflow it came from.

Builds on #27663.

Part of #27525
bolichen97 added a commit that referenced this pull request Nov 8, 2026
A finished ad-hoc run could only be promoted into a new definition, so
saving an edited script under an existing slug produced `<slug>-2`
instead of a new revision. The only way to append one was pasting the
script into Customize -> Workflows.

Add an owner-only `POST /api/workflows/runs/{run_id}/update-definition`
that appends the run's exact source as a chosen definition's next
revision, pinned by `expected_revision` and by the run source's SHA-256
its `GET` preview returned, so a paused plan replanned while the owner
reads the diff is refused rather than saved unseen. The run passes
promotion's checks (now shared as `_reusable_run`), must match the
definition's format, and an unchanged source is refused. The preview
suggests the target from the run's lineage or the script's META name
and returns an uncapped diff, `workflow_source_diff`, split out of the
change card's capped `_workflow_diff`. The logic lives in the new
`workflows/update_from_run.py`, below the service in the workflows
layering contract: it is handed the service and never imports it, so
the `META.adapted_from` parser both need moves to `library.py`.

An edited rerun of a saved Python workflow keeps that workflow as
`derived_from` ancestry, as an adapted TaskRunner plan already does, so
the preview suggests the workflow it came from.

Builds on #27663.

Part of #27525
bolichen97 added a commit that referenced this pull request Nov 8, 2026
A finished ad-hoc run could only be promoted into a new definition, so
saving an edited script under an existing slug produced `<slug>-2`
instead of a new revision. The only way to append one was pasting the
script into Customize -> Workflows.

Add an owner-only `POST /api/workflows/runs/{run_id}/update-definition`
that appends the run's exact source as a chosen definition's next
revision, pinned by `expected_revision` and by the run source's SHA-256
its `GET` preview returned, so a paused plan replanned while the owner
reads the diff is refused rather than saved unseen. The run passes
promotion's checks (now shared as `_reusable_run`), must match the
definition's format, and an unchanged source is refused. The preview
suggests the target from the run's lineage or the script's META name
and returns an uncapped diff, `workflow_source_diff`, split out of the
change card's capped `_workflow_diff`. The logic lives in the new
`workflows/update_from_run.py`, below the service in the workflows
layering contract: it is handed the service and never imports it, so
the `META.adapted_from` parser both need moves to `library.py`.

An edited rerun of a saved Python workflow keeps that workflow as
`derived_from` ancestry, as an adapted TaskRunner plan already does, so
the preview suggests the workflow it came from.

Builds on #27663.

Part of #27525
bolichen97 added a commit that referenced this pull request Nov 8, 2026
A finished ad-hoc run could only be promoted into a new definition, so
saving an edited script under an existing slug produced `<slug>-2`
instead of a new revision. The only way to append one was pasting the
script into Customize -> Workflows.

Add an owner-only `POST /api/workflows/runs/{run_id}/update-definition`
that appends the run's exact source as a chosen definition's next
revision, pinned by `expected_revision` and by the run source's SHA-256
its `GET` preview returned, so a paused plan replanned while the owner
reads the diff is refused rather than saved unseen. The run passes
promotion's checks (now shared as `_reusable_run`), must match the
definition's format, and an unchanged source is refused. The preview
suggests the target from the run's lineage or the script's META name
and returns an uncapped diff, `workflow_source_diff`, split out of the
change card's capped `_workflow_diff`. The logic lives in the new
`workflows/update_from_run.py`, below the service in the workflows
layering contract: it is handed the service and never imports it, so
the `META.adapted_from` parser both need moves to `library.py`.

An edited rerun of a saved Python workflow keeps that workflow as
`derived_from` ancestry, as an adapted TaskRunner plan already does, so
the preview suggests the workflow it came from.

Builds on #27663.

Part of #27525
@iamwhatever

Copy link
Copy Markdown
Contributor

Thanks @weijian722! This change landed on main through #32352 (#32352, merge commit 38a0633, merged 2026-11-08), which builds on this PR and adds update-from-run to the workflow service and dashboard handlers. Closing this one as landed. Thank you for the groundwork.

@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Nov 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor) merge conflict Branch has merge conflicts with its base — author must resolve before merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants