fix(cua-driver): advertise refusals in the MCP outputSchema

[f-trycua]

Problem

Action tools (click, press_key, type_text, hotkey, and the rest of the ACTION_RESULT_TOOLS set) declare an outputSchema describing only the success shape — closed, required: ["effect","route"]. But MCP holds every structuredContent a tool emits to that schema, including the payload that accompanies isError: true.

Refusals answer with a diagnostic envelope instead. Both shapes below are verbatim captures from a live cua-driver mcp stdio session:

{"refusal": {"code": "stale_element_token",
             "message": "element_token is stale; call get_window_state again to refresh"},
 "status": "refused"}

{"candidates": [], "code": "window_target_not_found", "effect": "refused", "pid": 999999}

Neither validates: missing effect/route, plus undeclared keys. Strict clients reject the entire response with -32602 and the actionable message never reaches the caller.

Impact

Found while dogfooding a local model driving Calculator through opencode + cua-driver. The driver did its job — it said "element_token is stale; call get_window_state again to refresh". The agent saw only:

MCP error -32602: Structured content does not match the tool's output schema:
  data must have required property 'effect', data must have required property 'route',
  data must NOT have additional properties, data must NOT have additional properties

With no signal to re-snapshot, it concluded the accessibility route was broken, abandoned it, burned ~15 steps on pixel-coordinate guessing, and finished with a confident and wrong root-cause analysis. This degrades every agent on the driver, not just local models — the better the error message we write, the more it costs us to have it discarded.

Fix

Advertise the success shape beside the refusal envelope as an anyOf.

• No runtime behaviour changes. Not one response payload moves; only the declared schema widens to describe what the driver already sends.
• Success stays strict. The success variant is byte-for-byte the existing closed ActionResult schema. An unknown key on a success payload is still a contract violation and cannot be laundered through the permissive refusal variant — asserted in the new test.
• SDK generation untouched. The generated contract manifest keeps carrying success_output_schema unwrapped; only the live MCP surface advertises the wrapper. The field was already named success_output_schema, so the codebase always knew this schema described one half of the contract.

Verification

Wire-tested against a rebuilt daemon on a private socket:

advertised variants: 2
  [0] success  required: ['effect', 'route']  additionalProperties: false
  [1] refusal  markers: [['refusal'], ['status'], ['code']]

refusal isError: True
refusal text  : element_token is stale; call get_window_state again to refresh
refusal struct: {"refusal": {...}, "status": "refused"}

New regression test runs both live refusal captures and a success payload through a real JSON Schema validator, the way a strict MCP client does, and asserts a malformed success payload still fails.

Suites run locally, all green:

Suite	Result
cua-driver-contract --lib	29 passed
cua-driver-core --lib	497 passed
protocol_schema_test	3 passed
schema_consistency_test	2 passed
protocol_element_token_test	4 passed
compatibility_contract_test	3 passed
embedded_host_sdk_mcp_test	5 passed

cargo fmt applied; cargo clippy surfaces no new warnings.

Docs

docs/content/docs/reference/cua-driver/contracts.mdx gains a What a tool returns section documenting both variants, the refusal marker keys, and a callout telling agent authors to branch on refusal.code and surface the content text — stale_element_token means re-snapshot and retry, not that the route is dead.

🤖 Generated with Claude Code