feat(workflow-executor): add UpdateRecordStepExecutor with confirmation flow by Scra3 · Pull Request #1499 · ForestAdmin/agent-nodejs

Scra3 · 2026-03-19T10:41:46Z

Summary

Implements PRD-219: UpdateRecordStepExecutor with 3 execution branches — automatic completion (Branch B), awaiting user confirmation (Branch C), and re-entry after confirmation accept/reject (Branch A)
Extracts shared helpers (selectRecordRef, getAvailableRecordRefs, getCollectionSchema, toRecordIdentifier, schemaCache) from ReadRecordStepExecutor into BaseStepExecutor for DRY reuse
Adds UpdateRecordStepExecutionData type, NoWritableFieldsError, and userInput on ExecutionContext

Test plan

All 84 existing + new tests pass
ReadRecordStepExecutor tests still pass after refactor (no behavior change)
11 new test cases cover: automatic completion, awaiting-input, confirmation accepted/rejected, missing interruption, multi-record AI selection, NoWritableFieldsError, malformed/missing tool calls, WorkflowExecutorError propagation, infra error propagation, default prompt fallback, previous steps context

fixes PRD-219

🤖 Generated with Claude Code

Note

Add `UpdateRecordStepExecutor` with user confirmation flow to workflow-executor

Adds UpdateRecordStepExecutor that uses an AI tool to select a writable field and value, then either updates immediately (automaticExecution: true) or returns awaiting-input for user confirmation.
On re-entry with context.userConfirmed, the executor fetches the prior execution and either applies the update or marks the step skipped.
Shared logic (record selection, schema caching, outcome building) is extracted into BaseStepExecutor helpers and reused by ReadRecordStepExecutor.
Renames AiTask* types to RecordTask* throughout (outcomes, execution data, step definitions) and replaces history with previousSteps in ExecutionContext.
Adds NoWritableFieldsError and McpTask step type to the public API.
Behavioral Change: ConditionStepExecutor and ReadRecordStepExecutor now rethrow non-WorkflowExecutorError failures instead of converting them to error outcomes.

^{Macroscope summarized d99fe27.}

linear · 2026-03-19T10:41:49Z

PRD-219 Implémenter l'executor UpdateRecord + TriggerAction

qltysh · 2026-03-19T10:42:54Z

All good ✅

packages/workflow-executor/src/executors/update-record-step-executor.ts

qltysh · 2026-03-19T10:48:25Z

Coverage Impact

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

Modified Files with Diff Coverage (7)

File	% Diff	Uncovered Line #s
...s/workflow-executor/src/executors/read-record-step-executor.ts	100.0%
...ges/workflow-executor/src/executors/condition-step-executor.ts	100.0%
packages/workflow-executor/src/types/step-definition.ts	100.0%
packages/workflow-executor/src/executors/base-step-executor.ts	100.0%
...workflow-executor/src/executors/update-record-step-executor.ts	98.2%	84
packages/workflow-executor/src/errors.ts	100.0%
packages/workflow-executor/src/index.ts	100.0%
Total	99.1%

🤖 Increase coverage with AI coding...

In the `feat/prd-219-update-record-step-executor` branch, add test coverage for this new code:

- `packages/workflow-executor/src/executors/update-record-step-executor.ts` -- Line 84

🚦 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.

packages/workflow-executor/src/executors/update-record-step-executor.ts

…on flow Implements PRD-219. Adds an executor for update-record steps with three execution branches: automatic completion, awaiting user confirmation, and re-entry after confirmation. Extracts shared record selection helpers from ReadRecordStepExecutor into BaseStepExecutor for reuse. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…cordStepExecutor Match on type + stepIndex only, then guard on toolConfirmationInterruption presence separately. Removes redundant filter predicate. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…endingUpdate The field stores the proposed field update (from AI or user-edited) pending confirmation. "pendingUpdate" better describes the content than "toolConfirmationInterruption" which described the mechanism. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…f error outcome Missing pendingUpdate in Branch A is a bug (orchestrator/RunStore), not a business case — throw WorkflowExecutorError instead of returning a graceful error outcome. Also rename local variable interruption → execution. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

… casting Add { skipped: true } to the executionResult union type, removing the unsafe `as unknown as` cast when the user rejects the update. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

… traceability Keep pendingUpdate in the saved execution data after both confirm and reject — useful for audit trail (what was proposed vs what happened). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…ecutor Pass userInput as parameter to handleConfirmation() where it is already narrowed, removing the `as { confirmed: boolean }` cast. Also move resolveFieldName inside try-catch blocks so WorkflowExecutorError is properly caught and returned as a status: 'error' outcome. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…prove coverage - Extract resolveAndUpdate to deduplicate resolve+update+persist logic - Extract buildOutcomeResult/buildSuccessResult/buildErrorResult helpers - Move getCollectionSchema inside try-catch in confirmation flow - Rename executionParams.fieldName to fieldDisplayName for consistency - Add tests for resolveFieldName failure in both branches - Add test for relationship field exclusion from update tool schema Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…dErrorResult wrappers Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…ment executionResult Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…StepExecutionData Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…field resolution Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Move findField to BaseStepExecutor with displayName priority over fieldName - Move buildOutcomeResult to BaseStepExecutor, use error !== undefined check - Fix resolveAndUpdate try-catch scope (saveStepExecution outside try block) - Fix ConditionStepExecutor catch-all to only catch WorkflowExecutorError - Add pendingUpdate visibility in step summary - Remove findField from types/record.ts and barrel export Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Condition steps handle BPMN routing, record-task steps operate on client data. The previous "ai-task" name was misleading since both step types use AI. Rename to "record-task" to reflect the actual distinction. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…Definition Drop recordSourceStepId and remoteToolsSourceId — both were declared but never read. allowedTools is kept as the orchestrator-provided tool filter. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Introduces StepType.ToolTask ('tool-task') and ToolTaskStepDefinition for steps where the AI freely selects and executes a tool from allowedTools. Moves allowedTools out of RecordTaskStepDefinition where it didn't belong. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…on type Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

packages/workflow-executor/src/executors/base-step-executor.ts

…AndUpdate arity - Extract UpdateTarget interface {selectedRecordRef, fieldDisplayName, value} so resolveAndUpdate takes 2 params instead of 4 (addresses qlty reviewer comment) - Collapse 3 uninitialized let declarations in handleFirstCall into one target object - Fix missing runId in getAvailableRecordRefs and update-record saveStepExecution calls - Strengthen test assertions to include runId as first arg Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Scra3 · 2026-03-20T08:54:28Z

packages/workflow-executor/src/types/step-outcome.ts

-export interface AiTaskStepOutcome extends BaseStepOutcome {
-  type: 'ai-task';
-  status: AiTaskStepStatus;
+export interface RecordTaskStepOutcome extends BaseStepOutcome {


Ai task was too ambiguous, record task is related to the forest record

Scra3 · 2026-03-20T08:55:04Z

packages/workflow-executor/src/types/step-definition.ts

  automaticCompletion?: boolean;
+}
+
+export interface ToolTaskStepDefinition extends BaseStepDefinition {


A task that wants to execute a tool

…ecutor Code changes: - Add JSDoc on buildOutcomeResult warning it is for record-task executors only - Add runtime guard on userInput.type in handleConfirmation (WorkflowExecutorError if an unexpected type is received, guarding against future UserInput union extension) New tests: - buildStepSummary: pendingUpdate branch coverage (update-record step with pendingUpdate but no executionParams emits Pending: in AI context) - handleConfirmation: stepIndex mismatch and missing pendingUpdate cases - stepOutcome shape: type/stepId/stepIndex asserted on happy path - unexpected userInput type: runtime guard verified - findField fieldName fallback: update succeeds when AI returns raw fieldName - schema caching: getCollectionSchema called once per collection in Branch B - RunStore error propagation: all four saveStepExecution/getStepExecutions call sites Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…pletion→automaticExecution - StepType.ToolTask → StepType.McpTask (wire value: 'tool-task' → 'mcp-task') - ToolTaskStepDefinition → McpTaskStepDefinition - mcpServerId: string[] → string (single ID) - automaticCompletion → automaticExecution on both RecordTaskStepDefinition and McpTaskStepDefinition - Remove TODO rename comments - Update all tests accordingly Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

macroscopeapp · 2026-03-20T09:35:52Z

packages/workflow-executor/src/index.ts

@@ -1,14 +1,14 @@
 export { StepType } from './types/step-definition';
 export type {


🟡 Medium src/index.ts:2

McpTaskStepDefinition is part of the StepDefinition union but is not exported from index.ts, while ConditionStepDefinition and RecordTaskStepDefinition are. Consumers cannot import the type directly to work with MCP task step definitions specifically.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file packages/workflow-executor/src/index.ts around line 2: `McpTaskStepDefinition` is part of the `StepDefinition` union but is not exported from `index.ts`, while `ConditionStepDefinition` and `RecordTaskStepDefinition` are. Consumers cannot import the type directly to work with MCP task step definitions specifically. Evidence trail: packages/workflow-executor/src/index.ts lines 2-5 (exports `ConditionStepDefinition`, `RecordTaskStepDefinition`, `StepDefinition` but not `McpTaskStepDefinition`); packages/workflow-executor/src/types/step-definition.ts lines 29-33 (`McpTaskStepDefinition` interface definition) and lines 35-38 (`StepDefinition` union includes `McpTaskStepDefinition`)

Not necessary yet

Understood. 👍

…record-1' Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Replaces the UserInput discriminated union with a plain boolean field userConfirmed on ExecutionContext and PendingStepExecution. Since the only user input type in practice is a boolean confirmation, the union wrapper adds complexity with no benefit. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

macroscopeapp bot reviewed Mar 19, 2026

View reviewed changes

packages/workflow-executor/src/executors/update-record-step-executor.ts Outdated Show resolved Hide resolved

Scra3 force-pushed the feat/prd-219-update-record-step-executor branch from 2dc8c24 to bb2901c Compare March 19, 2026 14:38

Base automatically changed from feat/prd-218-read-record-step-executor to feat/prd-214-setup-workflow-executor-package March 19, 2026 14:45

Scra3 force-pushed the feat/prd-219-update-record-step-executor branch from 8d13ac5 to f8323f8 Compare March 19, 2026 14:50

macroscopeapp bot reviewed Mar 19, 2026

View reviewed changes

packages/workflow-executor/src/executors/update-record-step-executor.ts Show resolved Hide resolved

alban bertolini and others added 17 commits March 20, 2026 09:30

refactor(workflow-executor): simplify interruption lookup in UpdateRe…

a70b36a

…cordStepExecutor Match on type + stepIndex only, then guard on toolConfirmationInterruption presence separately. Removes redundant filter predicate. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

refactor(workflow-executor): type executionResult as union instead of…

ebf033f

… casting Add { skipped: true } to the executionResult union type, removing the unsafe `as unknown as` cast when the user rejects the update. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

refactor(workflow-executor): remove redundant buildSuccessResult/buil…

9819917

…dErrorResult wrappers Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

refactor(workflow-executor): rename history to previousSteps and docu…

11b41b5

…ment executionResult Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs(workflow-executor): document pendingUpdate field on UpdateRecord…

239ca2f

…StepExecutionData Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

refactor(workflow-executor): extract findField helper to deduplicate …

50905bc

…field resolution Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

fix(workflow-executor): fix prettier formatting on StepDefinition uni…

6a49657

…on type Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Scra3 force-pushed the feat/prd-219-update-record-step-executor branch from b6dc9a5 to 6a49657 Compare March 20, 2026 08:34

macroscopeapp bot reviewed Mar 20, 2026

View reviewed changes

packages/workflow-executor/src/executors/base-step-executor.ts Outdated Show resolved Hide resolved

Scra3 commented Mar 20, 2026

View reviewed changes

alban bertolini and others added 2 commits March 20, 2026 09:56

macroscopeapp bot reviewed Mar 20, 2026

View reviewed changes

test(workflow-executor): rename misleading stepId 'ai-step' to 'read-…

1309b54

…record-1' Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Scra3 force-pushed the feat/prd-219-update-record-step-executor branch from ac706e8 to 1309b54 Compare March 20, 2026 10:40

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(workflow-executor): add UpdateRecordStepExecutor with confirmation flow#1499

feat(workflow-executor): add UpdateRecordStepExecutor with confirmation flow#1499
Scra3 wants to merge 22 commits intofeat/prd-214-setup-workflow-executor-packagefrom
feat/prd-219-update-record-step-executor

Scra3 commented Mar 19, 2026 •

edited by macroscopeapp bot

Loading

Uh oh!

linear bot commented Mar 19, 2026

Uh oh!

qltysh bot commented Mar 19, 2026 •

edited

Loading

Uh oh!

Uh oh!

qltysh bot commented Mar 19, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Scra3 Mar 20, 2026

Uh oh!

Scra3 Mar 20, 2026

Uh oh!

macroscopeapp bot Mar 20, 2026

Uh oh!

Scra3 Mar 20, 2026

Uh oh!

macroscopeapp bot Mar 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

		@@ -1,14 +1,14 @@
		export { StepType } from './types/step-definition';
		export type {

Conversation

Scra3 commented Mar 19, 2026 • edited by macroscopeapp bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Add UpdateRecordStepExecutor with user confirmation flow to workflow-executor

Uh oh!

linear bot commented Mar 19, 2026

Uh oh!

qltysh bot commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

qltysh bot commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Scra3 Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Scra3 Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

macroscopeapp bot Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Scra3 Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

macroscopeapp bot Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Scra3 commented Mar 19, 2026 •

edited by macroscopeapp bot

Loading

Add `UpdateRecordStepExecutor` with user confirmation flow to workflow-executor

qltysh bot commented Mar 19, 2026 •

edited

Loading

qltysh bot commented Mar 19, 2026 •

edited

Loading