feat(workflow-executor): add TriggerActionStepExecutor with confirmation flow

[Scra3]

Summary

• Implements TriggerActionStepExecutor following the UpdateRecordStepExecutor pattern (branches A/B/C, automaticExecution, confirmation flow)
• AI selects an action via a select-action tool (Zod enum of display names + technical names as hints); resolveActionName maps displayName → technical name with name fallback
• Adds TriggerActionStepExecutionData with executionParams: { actionDisplayName, actionName }, executionResult: { success } | { skipped }, and pendingAction for the awaiting-confirmation state
• Adds NoActionsError for collections with no actions
• Fixes buildStepSummary in BaseStepExecutor to include trigger-action pendingAction in prior-step AI context (parity with update-record pendingUpdate)
• Action result intentionally discarded — privacy constraint (no client data leaves the infrastructure)

Test plan

• Branch B (automaticExecution: true) — triggers action, saves executionParams with both display and technical name, returns success
• Branch C (no automaticExecution) — saves pendingAction, returns awaiting-input
• Branch A confirmed — triggers action, preserves pendingAction for traceability
• Branch A rejected — action not called, saves { skipped: true }
• Branch A no pending action — throws
• NoActionsError — returns error outcome
• WorkflowExecutorError from executeAction → error outcome (branches A & B)
• Infrastructure errors propagate (branches A & B)
• resolveActionName failure (Branch A — action deleted between confirmation steps)
• displayName → technical name resolution + fallback
• Multi-record AI selection
• RunStore error propagation (5 scenarios across all branches)
• AI malformed / missing tool call → error outcome
• Default prompt fallback
• Previous steps context in AI messages
• Schema caching (single getCollectionSchema call per collection)
• stepOutcome shape

🤖 Generated with Claude Code

Note

Add TriggerRecordActionStepExecutor with confirmation flow to workflow-executor

• Adds four new step executors: TriggerRecordActionStepExecutor, LoadRelatedRecordStepExecutor, McpTaskStepExecutor, and RecordTaskStepExecutor (abstract base), each supporting automatic execution and a user-confirmation flow via handleConfirmationFlow.
• Refactors BaseStepExecutor to wrap all execution in a common execute() → doExecute() pattern that maps WorkflowExecutorError subclasses to structured error outcomes and logs unexpected errors instead of throwing.
• Introduces SafeAgentPort to normalize underlying agent-port errors to AgentPortError, and rewrites all AgentPort method signatures to accept query objects instead of positional parameters.
• Expands the error hierarchy in errors.ts with ~15 new typed errors (e.g. StepPersistenceError, FieldNotFoundError, AgentPortError) each carrying a user-facing userMessage.
• Implements the Runner polling loop: periodic step fetching, in-flight deduplication, lazy MCP tool loading, and outcome reporting via workflowPort.updateStepExecution.
• Behavioral Change: AgentPort methods now require object-shaped query parameters; existing adapters and callers must be updated to the new signatures.

^{Macroscope summarized a5d6249.}

[qltysh]

Coverage Impact

⬆️ Merging this pull request will increase total coverage on feat/prd-219-update-record-step-executor by 0.06%.

Modified Files with Diff Coverage (21)

Rating	File	% Diff	Uncovered Line #s
	packages/workflow-executor/src/runner.ts	96.5%	66-67
	...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/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%
	...workflow-executor/src/executors/update-record-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%
	packages/ai-proxy/src/index.ts	100.0%
	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/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%
	packages/workflow-executor/src/types/step-outcome.ts	100.0%
	...s/workflow-executor/src/executors/record-task-step-executor.ts	100.0%
	...-executor/src/executors/trigger-record-action-step-executor.ts	100.0%
	...ow-executor/src/executors/summary/step-execution-formatters.ts	100.0%
	Total	99.2%

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

[qltysh]

8 new issues

Tool	Category	Rule	Count
qlty	Structure	Function with high complexity (count = 20): execute	2
qlty	Structure	Deeply nested control flow (level = 4)	2
qlty	Duplication	Found 16 lines of similar code in 2 locations (mass = 92)	2
qlty	Structure	Function with many returns (count = 7): create	2

[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 src/errors.ts:3

causeMessage throws a TypeError when error is null or undefined because the destructuring const { cause } = error as ... attempts to read from a non-object. Since this function handles errors from catch blocks where throw null or throw undefined is valid, consider adding a null check before the destructuring.

 export function causeMessage(error: unknown): string | undefined {
+  if (error == null) return undefined;
   const { cause } = error as { cause?: unknown };
 
   return cause instanceof Error ? cause.message : undefined;

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

In file packages/workflow-executor/src/errors.ts around lines 3-7:

`causeMessage` throws a `TypeError` when `error` is `null` or `undefined` because the destructuring `const { cause } = error as ...` attempts to read from a non-object. Since this function handles errors from catch blocks where `throw null` or `throw undefined` is valid, consider adding a null check before the destructuring.

Evidence trail:
packages/workflow-executor/src/errors.ts lines 3-6: `causeMessage` function with destructuring `const { cause } = error as { cause?: unknown }`
packages/workflow-executor/src/runner.ts line 167: `causeMessage(error)` called in catch block
packages/workflow-executor/src/executors/error-step-executor.ts line 20: `causeMessage(this.error)` called with `unknown` typed error

[macroscopeapp]

🟢 Low executors/load-related-record-step-executor.ts:397

In selectBestRecordIndex, the guard at line 397 allows non-integer values like 1.5 to pass because it only checks range bounds, not whether the index is an integer. When recordIndex is 1.5, candidates[1.5] returns undefined, and toRecordRef(undefined) crashes when accessing data.collectionName. Add an integer check to the validation guard.

-    if (recordIndex < 0 || recordIndex > maxIndex) {
+    if (!Number.isInteger(recordIndex) || recordIndex < 0 || recordIndex > maxIndex) {

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

In file packages/workflow-executor/src/executors/load-related-record-step-executor.ts around line 397:

In `selectBestRecordIndex`, the guard at line 397 allows non-integer values like `1.5` to pass because it only checks range bounds, not whether the index is an integer. When `recordIndex` is `1.5`, `candidates[1.5]` returns `undefined`, and `toRecordRef(undefined)` crashes when accessing `data.collectionName`. Add an integer check to the validation guard.

Evidence trail:
packages/workflow-executor/src/executors/load-related-record-step-executor.ts lines 395-401 (guard only checks range bounds with `recordIndex < 0 || recordIndex > maxIndex`), lines 182-186 and 193 (bestIndex returned from selectBestRecordIndex is used as array index: `relatedData[bestIndex]`), lines 405-410 (toRecordRef accesses `data.collectionName` which crashes when data is undefined)