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 updating records, triggering actions, loading related records, and MCP tasks

• Introduces four new step executors: UpdateRecordStepExecutor, TriggerRecordActionStepExecutor, LoadRelatedRecordStepExecutor, and McpTaskStepExecutor, each supporting automatic execution, user confirmation flow, and pending-data persistence.
• Refactors BaseStepExecutor to centralize error handling in execute() (catching and converting errors to user-facing outcomes), add AI-assisted record/field/action selection helpers, schema caching, and a SafeAgentPort wrapper that normalizes unexpected errors into AgentPortError.
• Renames AiTask* types to RecordTask* and adds a new mcp-task StepType; updates AgentPort method signatures to accept structured query objects instead of positional parameters.
• Adds a Logger port and ConsoleLogger adapter; integrates optional logging into BaseStepExecutor and ExecutorHttpServer, which now returns a generic 'Internal server error' body instead of exposing error messages.
• Replaces @langchain/core with @forestadmin/ai-proxy as the direct dependency for LangChain types across the package.
• Risk: AgentPort interface is a breaking change — all implementations must be updated to use the new object-based query signatures.

^{Macroscope summarized 369a398.}

[qltysh]

Coverage Impact

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

Modified Files with Diff Coverage (18)

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%
	...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%
	...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%
	...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.5%

🤖 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

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

6 new issues

Tool	Category	Rule	Count
qlty	Structure	Function with high complexity (count = 18): 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

[macroscopeapp]

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

The assertion not.toContain(expect.stringContaining('stepIndex: 3')) at line 1467 always passes because stringContaining('stepIndex: 3') never matches the 'Step N - Collection #id' format used by select-record tool options (e.g., 'Step 2 - Orders #99'). This gives false confidence that pending executions without a record are excluded from the pool. Consider asserting against the actual identifier format, such as checking that the options array has length 2 and excludes 'Step 3 - Invoices #55'.

-      expect(selectRecordTool.schema.shape.recordIdentifier.options).not.toContain(
-        expect.stringContaining('stepIndex: 3'),
-      );
+      expect(selectRecordTool.schema.shape.recordIdentifier.options).toHaveLength(2);
+      expect(selectRecordTool.schema.shape.recordIdentifier.options).not.toContain(
+        'Step 3 - Invoices #55',
+      );

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

In file packages/workflow-executor/test/executors/load-related-record-step-executor.test.ts around lines 1467-1469:

The assertion `not.toContain(expect.stringContaining('stepIndex: 3'))` at line 1467 always passes because `stringContaining('stepIndex: 3')` never matches the `'Step N - Collection #id'` format used by `select-record` tool options (e.g., `'Step 2 - Orders #99'`). This gives false confidence that pending executions without a `record` are excluded from the pool. Consider asserting against the actual identifier format, such as checking that the options array has length 2 and excludes `'Step 3 - Invoices #55'`.

Evidence trail:
1. Test assertion at packages/workflow-executor/test/executors/load-related-record-step-executor.test.ts:1467-1469 - shows `not.toContain(expect.stringContaining('stepIndex: 3'))`
2. Record identifier format at packages/workflow-executor/src/executors/base-step-executor.ts:228-233 - comment says 'Step X - CollectionDisplayName #id' and implementation shows: `Step ${record.stepIndex} - ${schema.collectionDisplayName} #${record.recordId}`
3. Test mock at line 1427: `{ recordIdentifier: 'Step 2 - Orders #99' }` confirms the actual format used
4. pendingExecution definition at lines 1388-1398 shows stepIndex: 3 with pendingData.displayName: 'Invoice'