refactor(workflow-executor): workflow steps

[Scra3]

Summary

• Extract ActionRef and FieldRef shared interfaces ({ name, displayName }) from inline types in TriggerActionStepExecutionData and UpdateRecordStepExecutionData
• Replace FieldReadBase (private) with exported FieldRef — FieldReadSuccess/FieldReadError now extend FieldRef
• Rename actionDisplayName/actionName → displayName/name and fieldDisplayName/fieldName → displayName/name for consistency
• Move resolveFieldName to handleFirstCall so the technical field name is stored in pendingUpdate at creation time (no re-resolution in resolveAndUpdate)
• Add missing tests: resolveActionName not-found path, saveStepExecution not-called assertions on WorkflowExecutorError, trigger-action pending action in buildStepSummary
• Export ActionRef, FieldRef, NoActionsError from index; update CLAUDE.md

Test plan

• yarn workspace @forestadmin/workflow-executor test — 144 tests pass
• yarn workspace @forestadmin/workflow-executor build — no errors
• yarn workspace @forestadmin/workflow-executor lint — clean

🤖 Generated with Claude Code

Note

Add new workflow step executors for record update, action trigger, related record loading, and MCP tasks

• Adds four new step executors: UpdateRecordStepExecutor, TriggerRecordActionStepExecutor, LoadRelatedRecordStepExecutor, and McpTaskStepExecutor, each supporting automatic execution and user confirmation flows.
• Refactors BaseStepExecutor to provide a unified execute() wrapper with structured error handling, confirmation flow helpers, tool invocation via @forestadmin/ai-proxy, schema caching, and previous-step summaries via StepSummaryBuilder.
• Introduces StepExecutorFactory to centralize executor instantiation; on factory errors, returns a fallback executor yielding a standardized error outcome.
• Implements Runner internals: HTTP server startup, polling loop with in-flight deduplication, MCP tool lazy loading, and outcome reporting to WorkflowPort.
• Expands the error hierarchy in errors.ts with ~15 new typed error classes, each carrying a userMessage for frontend display.
• Behavioral Change: AiTaskStepDefinition/AiTaskStepOutcome are replaced by RecordTaskStepDefinition/RecordTaskStepOutcome; isExecutedStepOnExecutor is no longer exported; AgentPort methods now accept single query objects instead of positional parameters.

^{Macroscope summarized a5d6249.}

[qltysh]

Coverage Impact

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

Modified Files with Diff Coverage (22)

Rating	File	% Diff	Uncovered Line #s
	packages/workflow-executor/src/executors/safe-agent-port.ts	100.0%
	packages/workflow-executor/src/adapters/console-logger.ts	50.0%	5
	...ages/workflow-executor/src/executors/mcp-task-step-executor.ts	100.0%
	packages/workflow-executor/src/runner.ts	96.5%	66-67
	packages/workflow-executor/src/executors/step-executor-factory.ts	100.0%
	...ow-executor/src/executors/load-related-record-step-executor.ts	99.0%	138
	...orkflow-executor/src/executors/summary/step-summary-builder.ts	100.0%
	...s/workflow-executor/src/executors/read-record-step-executor.ts	100.0%
	packages/workflow-executor/src/types/step-outcome.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%
	packages/workflow-executor/src/http/executor-http-server.ts	100.0%
	.../workflow-executor/src/adapters/forest-server-workflow-port.ts	100.0%
	...s/workflow-executor/src/executors/record-task-step-executor.ts	100.0%
	...workflow-executor/src/executors/update-record-step-executor.ts	100.0%
	...-executor/src/executors/trigger-record-action-step-executor.ts	100.0%
	...ages/workflow-executor/src/adapters/agent-client-agent-port.ts	100.0%
	packages/workflow-executor/src/errors.ts	100.0%
	packages/workflow-executor/src/index.ts	100.0%
	...ow-executor/src/executors/summary/step-execution-formatters.ts	100.0%
	packages/ai-proxy/src/index.ts	100.0%
	Total	99.3%

🤖 Increase coverage with AI coding...

In the `feat/trigger-action-step-executor` branch, add test coverage for this new code:

- `packages/workflow-executor/src/adapters/console-logger.ts` -- Line 5
- `packages/workflow-executor/src/executors/load-related-record-step-executor.ts` -- Line 138
- `packages/workflow-executor/src/runner.ts` -- Line 66-67

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

[macroscopeapp]

🟡 Medium src/runner.ts:182

inFlightSteps.delete(key) runs in the finally block before updateStepExecution is awaited, so a concurrent poll cycle can re-execute the step before the backend marks it complete. Move the delete to after updateStepExecution succeeds, or await the update inside the try block before cleanup.

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

In file packages/workflow-executor/src/runner.ts around line 182:

`inFlightSteps.delete(key)` runs in the `finally` block before `updateStepExecution` is awaited, so a concurrent poll cycle can re-execute the step before the backend marks it complete. Move the delete to after `updateStepExecution` succeeds, or await the update inside the try block before cleanup.

Evidence trail:
packages/workflow-executor/src/runner.ts lines 183-220 (REVIEWED_COMMIT): executeStep method shows `inFlightSteps.add(key)` at line 188, `finally { this.inFlightSteps.delete(key); }` at lines 210-212, and `await this.config.workflowPort.updateStepExecution(...)` at line 215 which is outside and after the try-catch-finally block.

packages/workflow-executor/src/runner.ts lines 153-166 (REVIEWED_COMMIT): runPollCycle method fetches pending steps from backend and filters using `!this.inFlightSteps.has(stepKey(s))`, showing the race window where a step could be re-fetched and re-executed.

[macroscopeapp]

🟢 Low adapters/forest-server-workflow-port.ts:34

getPendingStepExecutionsForRun queries a list endpoint that returns an array, but declares return type PendingStepExecution | null. The server will return an array at runtime, causing callers to receive an array typed as a single object. Consider changing the return type to Promise<PendingStepExecution[]> to match the actual response shape.

Suggested change

	async getPendingStepExecutionsForRun(runId: string): Promise<PendingStepExecution | null> {
	async getPendingStepExecutionsForRun(runId: string): Promise<PendingStepExecution[]> {

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

In file packages/workflow-executor/src/adapters/forest-server-workflow-port.ts around line 34:

`getPendingStepExecutionsForRun` queries a list endpoint that returns an array, but declares return type `PendingStepExecution | null`. The server will return an array at runtime, causing callers to receive an array typed as a single object. Consider changing the return type to `Promise<PendingStepExecution[]>` to match the actual response shape.

Evidence trail:
- packages/workflow-executor/src/adapters/forest-server-workflow-port.ts lines 10-16 (ROUTES definitions showing same base endpoint)
- packages/workflow-executor/src/adapters/forest-server-workflow-port.ts lines 25-39 (both methods using same endpoint with different return types)
- packages/forestadmin-client/src/utils/server.ts line 72 (ServerUtils.query returns response.body directly without transformation)
- packages/workflow-executor/src/runner.ts lines 91-96 (usage of result as single object)
- packages/workflow-executor/src/ports/workflow-port.ts lines 11-12 (interface definition)