fix(decision): offer dismiss_keyboard while an on-screen keyboard is showing

[pvedula7]

What and why

• The decision executor offers scroll_up, scroll_down and back next to the element operations, but not the runner's dismissKeyboard. On a device the keyboard that typing raises can cover the next control, and the tree drops whatever it covers, so the model has nothing that reaches it.
• packages/decision/src/elements.ts now adds dismiss_keyboard to the controls when the target declares dismissKeyboard and the tree lists a keyboard or key node outside any hidden subtree. That is the probe keyboardShowing uses in packages/mobile/src/surface.ts. An iOS number pad lists only its keys. perform in packages/decision/src/dispatch.ts runs it through ctx.actions.dismissKeyboard(), so the runner authorizes, budgets and records it, and CONTROL_LABELS in executor.ts names it "dismiss the keyboard" in turns and history. Web declares no dismiss and is unchanged.
• The criterion in packages/decision/src/questions.ts states the fact: "The on-screen keyboard is up. Controls it covers are missing from the elements; hide it to reach them." With the built-in tool's wording ("when it covers what you need to reach") Jev never picked it in 23 decisions, p at most 0.20.

Verified

Ran it locally: yes

• The live runs below were on the layout before feat(decision): full action grammar, none fallback, and vision through the OpenAI Decisions API #965. The port onto the new layout is covered by unit tests: elements.test.ts (offered while keys show, not for a hidden keyboard, a hidden subtree, no keyboard, or no dismissKeyboard verb) and executor.test.ts (the operation question lists it and choosing it calls dismissKeyboard).
• Our React Native app on an iOS 26.5 simulator, not the mobile benchmark: e2e run tests/client-workout.e2e.ts --no-cache with Jev 1.13 through @ai-sdk/typesafe-ai. The step types reps and weight into number-pad fields, then taps "Log set", which the pad covers.

main	this branch
"Log set" is gone from the tree. Jev taps "Finish" 8 times, each APP_UNREACHABLE, then claims failed and the check agrees (ACTION_FAILED)	2/2 runs pick dismiss_keyboard, after 3 and after 7 failed taps, then tap "Log set". The logger moves to set 2

• Its probability climbs from about 0.2 to 0.3 with each failed tap and wins once it passes tap. It sits close to tap, so how many taps it takes varies between runs.
• Neither run passes. Run 1 ends blocked on the completion check. Run 2 types into set 2 as well, the pad comes back, and Jev taps "Finish" 9 more times before it claims failed. That loop is what fix(decision): count failed actions as no progress in the stall guard #844's stall guard is for.

Checklist

• Changeset added (pnpm changeset) for any change to a published package, or the change is testbed, docs, or CI only.
• Breaking change: title carries !, the changeset body names what breaks and what replaces it, and the deprecation warning landed a window earlier (stability policy in CONTRIBUTING.md).
• Docs updated in the same PR: the docs/**/*.mdx page for the behavior, and skills/e2e/ if the skill describes it.
• Contract change: emitted .d.ts reviewed, tests/types/sdk-types.ts updated; wire change edits the schema and both fixtures.
• Engine contract change (e2e/engine): changesets for e2e, @e2e-dev/web, and @e2e-dev/mobile.

[cubic-dev-ai]

All reported issues were addressed across 6 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[okwasniewski]

Thanks, good catch, and the numbers in the description make the case. One nit: please drop the JSDoc block above OPERATIONS in packages/decision/src/questions.ts; it describes a single entry and repeats the PR description.

For later: the mobile engine already has a measured keyboard state (raw.keyboard.kind in packages/mobile/src/surface.ts) that never reaches ExecutorObservation. Passing it through would make detection independent of whether the keyboard shows up in the tree (likely relevant on Android). Not blocking for this PR.

[pvedula7]

Thanks. The comment block above OPERATIONS is gone in 5b585d5. Agreed on the keyboard state. Will do in a follow up PR since it touches the engine contract.

[pvedula7]

Opened the keyboard-state follow-up as #883. On Androids agent-device only measured the keyboard on iOS, and Gboard's tree nodes don't use keyboard/key roles, so also opened callstack/agent-device#3240 to report. #883 will use that once it ships.

[pvedula7]

@okwasniewski
Hey, not sure what the process here is but this one should be ready for human review.

Appreciate your work on this repo!

[okwasniewski]

Thanks! I merged main into this branch and renamed scriptedEvaluation to scriptedDecision in the new test, since #916 renamed the helper on main. Decision typecheck and tests pass.

[okwasniewski]

Thanks for this. #965 just landed and restructured the decision package, so this conflicts now. The change is still wanted: main has no keyboard control yet. Could you rebase onto main and port it?

In the new layout it touches:

• elements.ts: add dismiss_keyboard to Control, and add it to the controls set in actionSpace when verbs.has('dismissKeyboard') and the tree shows a keyboard (your keyboardShowing helper).
• dispatch.ts: a dismiss_keyboard case in perform that calls actions.dismissKeyboard(). That is now the only place that touches ctx.actions.
• questions.ts: the OPERATIONS entry. executor.ts: a CONTROL_LABELS entry.

It comes to about 15 lines, and decision typecheck and tests pass with it.

[pvedula7]

Rebased onto main and ported to the #965 layout as one commit: dismiss_keyboard joins Control and the controls set in elements.ts (tree probe unchanged), perform in dispatch.ts calls actions.dismissKeyboard(), and questions.ts and executor.ts get the criterion and the CONTROL_LABELS entry. The tests, the docs line and the changeset came along, and decision typecheck and tests pass, as do pnpm check and pnpm test.

[okwasniewski]

thanks!