feat: API/tool actuator tier — perform writes via API when available, GUI fallback

[abrichr]

API/tool actuator tier — the EXECUTE half of the capability ladder

Two external reviews said it plainly: "where a real API exists, GUI-driving it is the wrong tool — use the API." openadapt-flow already can VERIFY effects (EffectVerifier, merged) and RESOLVE targets structurally (structural rung, #69), but it still always PERFORMS the write through the GUI. This PR adds the top of the ladder: when a step has a real API/tool binding, perform the write via the API (deterministic, $0, no model), confirm it with the EffectVerifier, and skip GUI actuation — falling through to the structural→visual ladder when no binding exists.

This is the RFC's api implementation of a TransitionContract (docs/design/WORKFLOW_PROGRAM_IR.md §4): one semantic effect, backend-specific impl (api → dom_uia → vision_rdp).

What's added

• ir.ApiBinding (additive optional on Step): a declarative REST/JSON call — kind (rest/fhir/mcp/tool), method, url_template, body_template, query, headers, expected_status, timeout_s, and the expected effects it produces. {param} placeholders substitute from the run's typed params. Shaped so a FHIR/MCP/tool binding fits the same model.

• runtime/actuators/ApiActuator: performs the call deterministically and classifies every attempt into a fail-safe outcome (no-double-write contract):

  • UNAVAILABLE — request never sent (connection refused / DNS / connect-timeout, or a missing param) → nothing written → safe to fall through to the GUI ladder.
  • ACTUATED — sent, 2xx → write performed → confirm via EffectVerifier, skip GUI.
  • HALT — sent but outcome unknown (read-timeout after bytes went out, non-2xx, post-send error) → the write may have landed → HALT (never accept, never GUI-retry).

  The connect-phase/read-phase split is exact in requests (ConnectTimeout subclasses ConnectionError; ReadTimeout does not), so catching ConnectionError before Timeout classifies correctly.

• Wired as the API tier at the top of _run_step: if a step has a binding and an ApiActuator is configured, actuate → EffectVerifier confirms (non-CONFIRMED → HALT) → GUI resolve/act skipped. Otherwise falls through unchanged.

Safety / gating preserved

• An API write still faces the EffectVerifier. Its "identity" is the explicit API parameter (stronger than a pixel band) — no identity gate is weakened.
• Fail-safe HALTs before any request when the write couldn't be confirmed: no effect contract (neither step.effects nor binding.effects) or no verifier configured.
• Additive: a step with no binding — or a binding with no actuator configured — behaves exactly as today (GUI actuation). The API tier is an optimization whose safe fallback is the GUI, never a gate that blocks a runnable step.
• $0 guarantee: zero model calls on the API path.

Tests (tests/test_replayer_api_actuator.py, all green)

Against the real MockMed fault_server REST API + RestRecordVerifier:

• binding actuates → EffectVerifier CONFIRMS → GUI skipped ($0, 0 model calls, one record written with the run's param);
• unreachable API falls through to the GUI cleanly — write happens exactly once, no double-write;
• REFUTED effect after an API write HALTS (record, not screen, is the oracle);
• attempted-but-rejected (non-2xx) HALTS, never GUI-retries;
• fail-safe HALTs (binding with no effect; binding with no verifier);
• back-compat: binding present + no actuator → GUI unchanged; no-binding bundle replays byte-identically;
• unit tests for the actuator's UNAVAILABLE/ACTUATED/HALT classification.

Full suite: 1028 passed, 16 skipped (pre-existing environmental skips).

Ties to EffectVerifier + emit-mcp

The confirmation reuses the same EffectVerifier path that gates a GUI write (_verify_effects gained an optional explicit-effects arg; the GUI call is unchanged). ApiBinding.kind includes mcp/tool as the same shape — the complement to emit-mcp (which manufactures an MCP tool from a GUI demo): where the demo's target already exposes an API, the binding lets the runtime call it instead of replaying the GUI.

Reconciliation touch-points (stacks on #69; retarget to main after #69/#70 merge)

Replayer edits are minimal and localized:

• ir.py — ApiBinding class + Step.api_binding + StepResult.actuation (all additive/optional) + ApiBinding.model_rebuild().
• replayer.py — one import (Effect); api_actuator ctor kwarg + assignment; a top-of-_run_step branch (_try_api_tier); the new _try_api_tier method; _verify_effects gains an optional effects= arg; a rung_counts["api"] accounting line in run().
• new runtime/actuators/ package (no conflict surface).

🤖 Generated with Claude Code

https://claude.ai/code/session_01CKrVJJy5jWVCkXAqgUqtqZ