feat(workflow-executor): add ReadRecordStepExecutor

[Scra3]

Summary

• Add ReadRecordStepExecutor — first AI-task step executor that reads fields from a record
• AI-based record selection when multiple records are available (via select-record tool)
• AI-based field selection via read-selected-record-field tool (supports single/multiple fields, displayName + fieldName resolution)
• New error classes: NoRecordsError, NoReadableFieldsError
• Relationship fields excluded from readable fields (ISO frontend)
• Previous steps context included in both record selection and field selection prompts

Test plan

• Single record, single/multiple field reads
• Field resolution by displayName
• Field not found returns per-field error (no global failure)
• Relationship fields excluded from tool schema
• No readable fields → error status
• Multi-record AI selection (first and second record)
• No records → error status
• Model error / malformed tool call / missing tool call → error status
• RunStore errors propagate (getRecords, saveStepExecution)
• Input stepHistory immutability
• Previous steps context in messages
• Default prompt fallback
• saveStepExecution arguments (executionParams, executionResult, selectedRecordRef)

fixes PRD-218

🤖 Generated with Claude Code

Note

Add ReadRecordStepExecutor for AI-driven record field selection and reading

• Adds ReadRecordStepExecutor that selects a record (prompting the model when multiple are available), picks relevant fields via a tool call, reads them via agentPort, and persists results with per-field success/error entries.
• Renames StepHistory → StepOutcome, CollectionRef → CollectionSchema, RecordFieldRef → FieldSchema, and related types throughout the package to clarify semantics.
• Removes getActions from AgentPort and trims RunStore to only getStepExecutions/saveStepExecution; WorkflowPort.getCollectionRef is renamed to getCollectionSchema.
• BaseStepExecutor.buildStepSummary now emits separate Input:/Output: lines when execution data exists, replacing the previous single Result: line.
• Adds NoRecordsError and NoReadableFieldsError as typed WorkflowExecutorError subclasses, and exports isExecutedStepOnExecutor as a runtime type guard.
• Risk: RunStore, AgentPort, and WorkflowPort interface removals are breaking changes for any existing implementations outside this package.

^{Macroscope summarized 650e70b.}

[linear]

PRD-218 Implémenter l'executor ReadRecord

[qltysh]

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
	...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%
	.../workflow-executor/src/adapters/forest-server-workflow-port.ts	100.0%
	...ages/workflow-executor/src/adapters/agent-client-agent-port.ts	100.0%
	packages/workflow-executor/src/types/step-execution-data.ts	100.0%
	packages/workflow-executor/src/errors.ts	100.0%
	packages/workflow-executor/src/index.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]

want to save the stepIndex to be sure to find the right o step in the workflow

[Scra3]

useless

[macroscopeapp]

🟡 Medium executors/read-record-step-executor.ts:167

In formatFieldResults, the field lookup uses f.fieldName === name || f.displayName === name, checking fieldName before displayName. Since the AI tool in buildReadFieldTool is told to use displayNames as possible values, a field with displayName = "Status" could be shadowed by another field with fieldName = "Status", causing the wrong field's value to be returned.

-      const field = schema.fields.find(f => f.fieldName === name || f.displayName === name);
+      const field = schema.fields.find(f => f.displayName === name || f.fieldName === name);

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

In file packages/workflow-executor/src/executors/read-record-step-executor.ts around line 167:

In `formatFieldResults`, the field lookup uses `f.fieldName === name || f.displayName === name`, checking `fieldName` before `displayName`. Since the AI tool in `buildReadFieldTool` is told to use `displayNames` as possible values, a field with `displayName = "Status"` could be shadowed by another field with `fieldName = "Status"`, causing the wrong field's value to be returned.

Evidence trail:
packages/workflow-executor/src/executors/read-record-step-executor.ts lines 134-159 (buildReadFieldTool telling AI to use displayNames) and lines 161-176 (formatFieldResults using `f.fieldName === name || f.displayName === name`); packages/workflow-executor/src/types/record.ts lines 5-9 (FieldSchema with separate fieldName and displayName).

[Scra3]

Not fixed — both lookup orders have the same shadowing risk in opposite directions. The current order is ISO frontend. In practice, fieldName and displayName are almost never the same string across different fields, so the collision scenario is theoretical.