feat: attach AI reasoning as a comment on approval requests

[Scra3]

Context

When an AI triggers a custom action that requires approval — via the MCP executeAction tool or the workflow-executor trigger-action step — the created approval request carried no explanation. The approver saw a bare request with no idea why the AI triggered it.

This PR lets the AI attach its reasoning, surfaced as a comment on the approval request.

Why a comment (not an attribute)

Checked the Forest server (forestadmin-server): POST /api/action-approvals only validates status / action_name / collection_name / record_ids / inputs — any extra attribute is dropped, and the actionApproval model has no message field. The free-text channel is the dedicated actionApprovalComment resource (POST /api/action-approvals/:id/comments, data.attributes.comment), same auth stack as creation. So the message is posted there.

Changes

• agent-client
  • Action.execute(signedApprovalRequest?, approvalRequestMessage?) forwards an optional message.
  • makeCreateApprovalRequest posts the message to /api/action-approvals/:id/comments after the approval is created — best-effort: a comment failure never turns the successful approval into an error.
• mcp-server — executeAction exposes an optional reasoning field (LLM-facing description asks it to always explain why), forwarded to execute(). Covers direct MCP use and the workflow mcp step.
• workflow-executor — the trigger-action step captures the AI action-selection reasoning (previously discarded in selectAction), falling back to the step prompt for pre-recorded actions, and threads it through ExecuteActionQuery.approvalMessage. Reasoning stays out of StepOutcome (privacy invariant preserved).

Tests

• agent-client: comment posted with correct path/body; skipped when no approval id; approval id still returned when the comment POST fails.
• mcp-server: reasoning forwarded to execute().
• workflow-executor: approvalMessage transmitted to the port; AI reasoning captured; prompt fallback for pre-recorded actions.

All suites green (agent-client 344, mcp-server 548, workflow-executor 1155), builds + lint clean.

Verification

Verified end-to-end against a local agent + Forest server: triggering the approval-gated Create new card action via MCP with a reasoning creates the approval request with the reasoning shown as a comment in the front. 🤖 Generated with Claude Code

Note

Attach AI reasoning as a comment on approval requests

• When an action requires approval, the AI's reasoning (or the step prompt as a fallback) is now posted as a comment on the created approval request.
• Action.execute in action.ts now accepts an options object with an optional approvalRequestMessage; after creating the approval request, a follow-up POST is made to /api/action-approvals/{id}/comments.
• The MCP executeAction tool gains an optional reasoning input field that is forwarded through to the approval request comment.
• The TriggerRecordActionStepExecutor derives the approval message from the AI selection's reasoning, falling back to the step prompt, and omits the message if neither is available.
• Risk: comment posting is best-effort — failures are swallowed with console.warn and do not affect the approval request result. Callers previously passing a bare signedApprovalRequest to Action.execute must now wrap it in an options object.

^{Macroscope summarized 787b9be.}

[qltysh]

1 new issue

Tool	Category	Rule	Count
qlty	Structure	Function with many returns (count = 6): handleFirstCall	1

[qltysh]

Coverage Impact

This PR will not change total coverage.

Modified Files with Diff Coverage (5)

Rating	File	% Diff	Uncovered Line #s
	packages/mcp-server/src/tools/execute-action.ts	100.0%
	packages/agent-client/src/approval-request-creator.ts	100.0%
	...-executor/src/executors/trigger-record-action-step-executor.ts	100.0%
	packages/agent-client/src/domains/action.ts	100.0%
	...ages/workflow-executor/src/adapters/agent-client-agent-port.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.

[christophebrun-forest]

Manual test OK
LGTM