feat(workflow-executor): pause a Trigger Action step on its approval and resume on the reviewer's branch [PRD-2004] by matthv · Pull Request #2063 · ForestAdmin/agent-nodejs

matthv · 2026-11-05T10:07:42Z

What

Executor side of PRD-2004, milestone M1 (automatic mode). Server side: ForestAdmin/forestadmin-server#8741. Contract: Dev split.

Contract: the Trigger Action definition keeps approvalOutcomes (the non-strict schema used to drop it). The pending step's context.approvalRequests ({ id, status, approverId }) now reaches the executor, an unknown status being dropped. A record outcome carries awaitingInputReason: 'pending-approval', approvalRequests, selectedOption (approved / rejected) and approverId, all forwarded to the orchestrator.
Pause: in Full AI, on a step with approval outcomes, an action filed for approval pauses the step on its request instead of succeeding. A request with no id errors the step.
No approval needed: an action that ran reports selectedOption: 'approved'.
Replay (checkIdempotency), once the orchestrator requeues the run:
- approved / rejected → success on that branch with approverId, and the decision is saved in the RunStore;
- failed → operator error;
- no status (deleted or unknown request) → error;
- still open, or no review sent → pause again.
Later AI steps read "APPROVED and run by the reviewer" or "REJECTED, NOT executed" instead of "AWAITING APPROVAL".
Steps without approvalOutcomes behave exactly as today.

Not in this PR

Manual and AI-assisted modes (native front form): PRD-2013.
On a step with approval outcomes, a Full AI step skipped for want of a source record succeeds without selectedOption, so the orchestrator errors it rather than going down Approved. Choosing the branch belongs to PRD-2014 (Q7).

How to play it

Follow the "How to play it" section of ForestAdmin/forestadmin-server#8741 with this branch running as the executor.

Part of PRD-2004

🤖 Generated with Claude Code

Note

Add approval pause and resume to Trigger Action steps in `workflow-executor`

Trigger Action steps with approvalOutcomes enabled now pause after filing an approval request and resume on replay without resubmitting the action, succeeding on the approved or rejected branch. See trigger-record-action-step-executor.ts.
New schemas and mappers validate and carry approval request reviews through the pending-step context, step definitions, and record outcomes. Adds ApprovalRequestUntrackedError, ApprovalRequestFailedError, and ApprovalRequestGoneError for missing request IDs, failed approvals, and unrecognized review statuses.
Execution summaries now distinguish approved (action ran, result unavailable), rejected (not executed), and pending approvals.
Behavioral Change: the new pause/resume path applies only to steps with approvalOutcomes set; the existing pending-approval replay path remains for other steps. Missing approval request IDs, failed approvals after review, and reviews with no recognized status now produce step errors; open or missing reviews pause again.

Changes since #2063 opened

Added ApprovalBranchesNeedFullAiError and a guard in TriggerRecordActionStepExecutor.pauseForConfirmation that throws it when native-form fallback occurs on a step with approvalOutcomes [0fa16c0]
Added a test in trigger-record-action-step-executor.test.ts for the ApprovalBranchesNeedFullAiError path [0fa16c0]
Updated the workflow-executor CLAUDE.md documentation [0fa16c0]

^{Macroscope summarized 9053246.}

…paused step's requests [PRD-2004] Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…request and resume on the reviewer's branch [PRD-2004] Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

… a Trigger Action [PRD-2004] Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

linear-code · 2026-11-05T10:07:49Z

PRD-2004

qltysh · 2026-11-05T10:09:00Z

8 new issues

Tool	Category	Rule	Count
qlty	Structure	Function with many returns (count = 4): toStepOutcome	4
qlty	Structure	Function with high complexity (count = 17): toUpdateStepRequest	4

qltysh · 2026-11-05T10:14:31Z

Coverage Impact

Unable to calculate total coverage change because base branch coverage was not found.

Modified Files with Diff Coverage (8)

Rating	File	% Diff	Uncovered Line #s
	packages/workflow-executor/src/types/validated/execution.ts	100.0%
	packages/workflow-executor/src/types/validated/step-outcome.ts	100.0%
	...-executor/src/executors/trigger-record-action-step-executor.ts	100.0%
	...workflow-executor/src/adapters/run-to-available-step-mapper.ts	100.0%
	packages/workflow-executor/src/errors.ts	100.0%
	packages/workflow-executor/src/types/validated/step-definition.ts	100.0%
	...ow-executor/src/adapters/step-outcome-to-update-step-mapper.ts	100.0%
	...ow-executor/src/executors/summary/step-execution-formatters.ts	100.0%
	Total	100.0%

🚦 See full report on Qlty Cloud »

🛟 Help

Diff Coverage: Coverage for added or modified lines of code (excludes deleted files). Learn more.
Total Coverage: Coverage for the whole repository, calculated as the sum of all File Coverage. Learn more.
File Coverage: Covered Lines divided by Covered Lines plus Missed Lines. (Excludes non-executable lines including blank lines and comments.)
- Indirect Changes: Changes to File Coverage for files that were not modified in this PR. Learn more.

Scra3

Spec (PRD-2004): conforms, except "Always send selectedOption on these steps" on the native-form path, raised inline.

Scra3 · 2026-11-05T15:15:07Z

        result && !('skipped' in result) && result.submissionOutcome === 'pending-approval';
      const approvalRequest = isPendingApproval ? result.approvalRequest : undefined;

+      if (isPendingApproval && this.hasApprovalOutcomes) {


Claude Opus 5.5 (claude-opus-5-5): Preferential: a paused approval step keeps a done record and resumes through the idempotency replay, and no ADR records that choice.

Code

Paused runs persist a done plus pending-approval record, a reader asks why a waiting step is done, and a pause phase was the alternative.

A way out: record the decision with /adr in docs/adr/.

Claude Opus 5.5 (claude-opus-5-5): No ADR, the paused done record fails the hard-to-reverse leg of the gate.

Why

A later pause phase can still read today's done plus pending-approval records the way checkIdempotency does, so switching costs one read path, not a migration.
The record lives in the client's RunStore and never crosses the orchestrator contract.

Scra3 · 2026-11-05T15:21:32Z

Forest Validator · Review: findings posted

When (UTC)	Commit	Step	Result
05/11 15:21	`9053246`	Review	findings posted · run `2063-20261105150321-Scra3`

…Action with approval branches [PRD-2004] A step finished by hand reports no branch until the native form carries one (PRD-2013), so the orchestrator errored the run after the human submitted. The step now errors before handing the form over, and CLAUDE.md states the approval exception to the idempotency replay. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Scra3

Approved after /verify-fixes run 2063-20261105161509-Scra3-verify: 3 findings of 2063-20261105150321-Scra3 closed or declined, none reopened.

matthv and others added 3 commits November 5, 2026 10:52

feat(workflow-executor): carry approval outcomes and the review of a …

3b31ca8

…paused step's requests [PRD-2004] Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

feat(workflow-executor): pause a Trigger Action step on its approval …

d052fd8

…request and resume on the reviewer's branch [PRD-2004] Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

feat(workflow-executor): tell later steps how the reviewer decided on…

9053246

… a Trigger Action [PRD-2004] Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

matthv marked this pull request as ready for review November 5, 2026 10:25

Scra3 reviewed Nov 5, 2026

View reviewed changes

Scra3 approved these changes Nov 5, 2026

View reviewed changes

matthv merged commit d386f0f into feature/prd-29-handle-action-approvals-within-workflows Nov 5, 2026
39 checks passed

matthv deleted the feature/prd-2004-approvals-in-workflows-pause-and-resume-a-trigger-action branch November 5, 2026 16:25

Navigation Menu

Repository navigation

feat(workflow-executor): pause a Trigger Action step on its approval and resume on the reviewer's branch [PRD-2004] - #2063

feat(workflow-executor): pause a Trigger Action step on its approval and resume on the reviewer's branch [PRD-2004]#2063
matthv merged 4 commits into
feature/prd-29-handle-action-approvals-within-workflowsfrom
feature/prd-2004-approvals-in-workflows-pause-and-resume-a-trigger-action

matthv commented Nov 5, 2026 •

edited by macroscopeapp Bot

Loading

Uh oh!

linear-code Bot commented Nov 5, 2026

Uh oh!

qltysh Bot commented Nov 5, 2026

Uh oh!

qltysh Bot commented Nov 5, 2026

Uh oh!

Scra3 left a comment

Uh oh!

Uh oh!

Scra3 Nov 5, 2026

Uh oh!

matthv Nov 5, 2026

Uh oh!

Uh oh!

Scra3 commented Nov 5, 2026

Uh oh!

Scra3 left a comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

matthv commented Nov 5, 2026 • edited by macroscopeapp Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Not in this PR

How to play it

Add approval pause and resume to Trigger Action steps in workflow-executor

Changes since #2063 opened

Uh oh!

linear-code Bot commented Nov 5, 2026

Uh oh!

qltysh Bot commented Nov 5, 2026

8 new issues

Uh oh!

qltysh Bot commented Nov 5, 2026

Uh oh!

Scra3 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Scra3 Nov 5, 2026

Choose a reason for hiding this comment

Uh oh!

matthv Nov 5, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Scra3 commented Nov 5, 2026

Forest Validator · Review: findings posted

Uh oh!

Scra3 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

matthv commented Nov 5, 2026 •

edited by macroscopeapp Bot

Loading

Add approval pause and resume to Trigger Action steps in `workflow-executor`