fix(ios): classify the keyboard dismiss refusal by what it dispatched
Summary
keyboard dismiss refused two different verdicts with one untyped message, so a caller had to match prose to tell them apart: a keyboard that exposes no dismiss control (nothing was sent) and a dismiss control that was tapped and left the keys up (it dispatched). The refusal behavior is unchanged; only its classification becomes typed.
The runner answers the no-dismiss-key case with its own wire code KEYBOARD_DISMISS_UNAVAILABLE, classified by the existing runner-code table. The published code contract is unchanged — it still travels under UNSUPPORTED_OPERATION through its own wire-code map — and the failure now carries details.reason: keyboard_dismiss_unavailable, details.runnerErrorCode, and dispatched: no, all visible in --json. dismissKeyboard answers a RunnerKeyboardDismissOutcome carrying dispatchedDismissal, which also decides which verdict a tvOS keyboard stayed up for.
14 files: Swift runner + protocol doc, the Apple runner classification and its tests, the dispatch-disclosure fixture, command help, and the command docs. No scope expansion beyond keyboard dismiss; no CHANGELOG.
$ agent-device keyboard dismiss --json
{"error":{"code":"UNSUPPORTED_OPERATION","message":"Unable to dismiss the keyboard: it exposes no dismiss key, …",
"details":{"runnerErrorCode":"KEYBOARD_DISMISS_UNAVAILABLE","reason":"keyboard_dismiss_unavailable","dispatched":"no"}}}
Live simulator evidence
Head 306352ce2a. iPhone 17, iOS 27.0, UDID 0E0FCBDC-88E2-4CB6-A1DA-E148F77743F4, Xcode 27.1 (27A9275). Runner rebuilt from this branch with pnpm build && pnpm build:xcuitest; fresh state dir, so a new daemon.
A="node bin/agent-device.mjs --platform ios --udid 0E0FCBDC-88E2-4CB6-A1DA-E148F77743F4 --state-dir /private/tmp/ad-4536-state --session k4536"
No dismiss control — Agent Device Tester, Form tab, Full name field, software keyboard up with no Done/Hide key:
$A open com.callstack.agentdevicelab --relaunch; $A press @e27; $A press @e10
$A keyboard dismiss --json # exit 1
{"success":false,"error":{"code":"UNSUPPORTED_OPERATION","message":"Unable to dismiss the keyboard: it exposes no dismiss key, and background taps are never attempted (…)","hint":"An element whose center sits behind the on-screen keyboard is refused with tap_keyboard_occludes_target; … or use keyboard enter to press the return key when submission is wanted.",
"details":{"runnerErrorCode":"KEYBOARD_DISMISS_UNAVAILABLE","reason":"keyboard_dismiss_unavailable","dispatched":"no"}}}
A screenshot taken right after shows the full QWERTY keyboard still visible, and snapshot -i still lists the key nodes.
With dismiss control — Safari, https://the-internet.herokuapp.com/login, Password field, accessory bar with Previous/Next/Done:
$A open com.apple.mobilesafari https://the-internet.herokuapp.com/login; $A press @e16
$A keyboard dismiss --json
{"success":true,"data":{"platform":"ios","action":"dismiss","wasVisible":true,"dismissed":true,"visible":false,"mechanism":"dismissKey","message":"Keyboard dismissed via its dismiss key"}}
snapshot -i afterwards no longer lists the Previous/Next/Done toolbar.
Cleanup: close --shutdown, daemon stop --clean --state-dir /private/tmp/ad-4536-state.
Validation
Base ddbfc85566, functional head b46ac6d761; 3231d4448c and 579ad97b28 are doc/help-sentence follow-ups on review; 306352ce2a applies the review recommendations (flag rename, separate wire-code map, help sentence).
pnpm check:affected --run --head b46ac6d76170efc6867e22acb773d0f57afd2c14— all runnable checks passed,exactCommit=true(format, lint, typecheck, layering, fallow, native-dupes, build, vitest-related, unit, command-docs, docs-links, docs-prose, xctest-selection, packaged-runner-swift).- Review follow-ups
3231d4448cand579ad97b28touch only thekeyboardhelp sentence and its docs counterpart. For those:cli-help-command-usage.test.ts,cli-help-topics.test.ts,command-doc-coverage.test.ts,check:doc-prose, and the MCP-metadata check pass locally; the serialized gate for the head is owned by CI. pnpm build:xcuitest(iOS + macOS) succeeded;pnpm check:xctest-selectionreports the new Swift test reachable from the host lane.- Re-run at
306352ce2a: focused vitest (runner-error-classification, runner-contract-response, index-dispatch-disclosure,src/commands/schema, help-conformance),pnpm check:xctest-selection,pnpm build && pnpm build:xcuitestpass. - CI obligations: device lanes (PR iOS runner smoke, nightly XCTest) run on GitHub. Coverage passed at
579ad97. - Unresolved risk: no released tag contains the old
detailsshape, and new optional keys inside the opendetailsrecord are already declared additive in the wire-compat ledger, so no ledger entry was added.
🤖 Generated with Claude Code