feat(agent-bff): expose the action form endpoint

[nbouliol]

Fixes PRD-673

What

Adds POST /v1/:collection/actions/:action/form to agent-bff. It loads a Smart Action form without failing on unknown UI-supplied values and returns the fields a UI needs to render (including the layout). No activity log is written.

Response shape:

{ fields: [{ name, type, value, isRequired, enumValues? }], canExecute, requiredFields, skippedFields, layout }

How

• Action resolution via the read-model action allow-list (isActionAllowed). Since the endpoint map is the allow-list, an absent action cannot be told from a known-but-disallowed one → every non-exposed action maps to unknown_action (404); action_not_allowed (403) has no local trigger, mirroring the collection/relation precedent.
• Form load reuses agent-client (createRemoteAgentClient().collection().action()), so the stateful /hooks/load + /hooks/change logic is not reimplemented. tryToSetFields skips unknown submitted values and returns them as skippedFields.
• Error mapping (PRD-670): each agent-hitting call (loadActionForm, tryToSetFields) is wrapped on its own; field/layout reads and mapping stay outside so a local bug surfaces as a 500. Fields and layout are read after tryToSetFields because a change hook rebuilds them.
• Shared read-model store: extracted src/http/agent-route-helpers.ts (token guard, read-model resolution, callAgent, decodeSegment) so the new action middleware and the existing data middleware share one cache.

Decisions / deviations from the ticket

See the planning-decisions comment on PRD-673 for the full list. Highlights:

• layout = raw ForestServerActionFormLayoutElement[] array. The spec is self-contradictory (prose says "ActionLayoutRoot serialized", example shows {type,component,elements}, actual JSON.stringify yields {layout:[...]}). We return the raw element array. ⚠️ To confirm with Anthony — trivial to change.
• enumValues present only for Enum fields (matches the MCP tool + AC enumValues?; the spec example shows null everywhere).
• recordIds: [] accepted for global/bulk actions (spec AC only covers missing recordIds); non-array → 400 invalid_request with no agent call.
• Timezone limitation: form hooks use agent-client’s hardcoded Europe/Paris (cannot forward the resolved timezone without an agent-client change, forbidden here). Tracked in PRD-768.
• "No activity log" test is behavioral: no activity-log writer exists in agent-bff yet (PRD-637); the test asserts the action is never executed / only form hooks are called.

Tests

test/action/action-routes-middleware.test.ts + test/action/action-form-mapper.test.ts: full response shape incl. layout, skipped values, canExecute true/false, post-change-hook read ordering, recordIds missing/non-array/[], values non-object, unknown_action 404, agent failures on load and tryToSetFields → PRD-670, 401/503.

Lint ✓ · build ✓ · 565/565 tests ✓.

Stacked on the PRD-672 branch — merge #1746 first, then this rebases onto main.

🤖 Generated with Claude Code

Note

Expose POST action form endpoint in agent-bff

• Adds a POST /agent/v1/:collection/actions/:action/form route in action-routes-middleware.ts that loads an action form from the agent, applies submitted values via tryToSetFields, and returns fields, canExecute, requiredFields, skippedFields, and layout.
• Adds action-form-mapper.ts to serialize ActionForm to a response object, including enumValues only for Enum-typed fields.
• Adds agent-action-client.ts as a thin client that calls the remote agent to load action forms.
• Extracts shared helpers (decodeSegment, resolveReadModel, requireAgentToken, callAgent) into agent-route-helpers.ts, replacing duplicated logic in the data routes middleware.
• Updates cli-core.ts to register both data and action route middlewares sharing a single read-model store.

^{Macroscope summarized ae6772e.}

[linear-code]

PRD-673

[qltysh]

Coverage Impact

⬆️ Merging this pull request will increase total coverage on main by 0.01%.

Modified Files with Diff Coverage (6)

Rating	File	% Diff	Uncovered Line #s
	packages/agent-bff/src/cli-core.ts	100.0%
	packages/agent-bff/src/data/data-routes-middleware.ts	100.0%
	packages/agent-bff/src/action/agent-action-client.ts	100.0%
	packages/agent-bff/src/http/agent-route-helpers.ts	100.0%
	packages/agent-bff/src/action/action-form-mapper.ts	100.0%
	packages/agent-bff/src/action/action-routes-middleware.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.

[ShohanRahman]

Review note — extractRawLayout "drift guard" test is missing

packages/agent-bff/src/action/agent-action-client.ts:36-39

export function extractRawLayout(action: ActionForm): ForestServerActionFormLayoutElement[] {
  const root = action.getLayout() as { layout?: ForestServerActionFormLayoutElement[] };
  return root.layout ?? [];
}

The comment at line 35 states "A layout-shape test guards against drift." — but no such test exists:

• extractRawLayout is never referenced by name in any test.
• Every test stubs getLayout() to return { layout: [...] } directly, so they exercise the BFF's own consumption of that shape, never agent-client's real ActionLayoutRoot (whose element array is a protected field reached here via cast).
• The ?? [] fallback branch is uncovered (branch coverage sits at ~83%).

Not a live bug — agent-client currently always populates that field with an array. But if that internal field is ever renamed, extractRawLayout silently returns [] (empty layout in the response) with zero test failures to catch it — which is exactly what the comment promises is guarded.

Suggested fix (either):

• Add a real test that instantiates agent-client's ActionLayoutRoot with a known layout and asserts extractRawLayout unwraps it correctly (closes the gap the comment claims), or
• Soften the comment to state the guard doesn't exist yet.

_{🤖 From a multi-agent review pass (code-reviewer, comment-analyzer, silent-failure-hunter, pr-test-analyzer all converged on this).}

[nbouliol]

Addressed in ae6772e — took the first option (real drift guard).

Added test/action/extract-raw-layout.test.ts:

• builds a real agent-client ActionLayoutRoot and asserts extractRawLayout unwraps its element array — so if that internal field is renamed, .layout reads undefined, the fallback returns [], and the assertion fails. That is the drift the comment promised.
• covers the ?? [] fallback branch explicitly.

Also tightened the code comment to name the guarding test. Full suite green (618 tests, run in-band).