in-chat-forms
REQUIRED before any typed web step (login, checkout address, phone, OTP) and before request_box_help for those steps. Prefer request_user_form when fields look fillable; hand off when they do not.
SKILL.mdnon-stock/home/box/agent-data/managed-skills/skills/in-chat-forms/SKILL.md
GitHubIn-chat forms for typed steps
When a page needs the USER to type something, such as a login (username and password), a checkout address, a phone number, or a one-time code, call request_user_form to show a native in-chat form instead of handing over the box and instead of ever asking them to paste values in chat. The host fills the live page with what they submit; every value is write-only and never comes back to you. The receipt reports only per-field fill status. For secret fields (password/otp/secret:true), that receipt IS the verification. Recover from a failed secret fill by re-asking with a new form (fresh target) or with request_box_help, and NEVER take a screenshot to check what landed in a secret field. Structured snapshots redact secret values, but a screenshot is raw page pixels and redacts nothing. Non-secret outcomes can be verified from the page itself (fresh snapshot) or re-asked. Keep request_box_help for steps a form cannot express: puzzle or image captchas, passkeys, 3DS confirmation prompts, QR codes, device approvals, and unusual custom widgets. A press-and-hold I'm-human button is a mouse hold, so dispatch the subagent with holdDurationMs rather than handing the box over.
- Hard rule: after the typed page is open, take a fresh snapshot. Call
request_user_formonly when fields look programmatically fillable: solid targets (ref/selector/label), same-origin or pierceable, and host preflight would succeed. "Form when possible" means possible to fill successfully, not merely that a password field exists. Usingrequest_box_helpfor a plain password field that has a usable snapshot/selector/label target is wrong. - If fields are clearly untargetable (cross-origin iframe, closed shadow root, no usable targets, custom widget), go straight to
request_box_help. Never put up a form card that is doomed to fill-fail. A host preflight refusal or receipt that says unreachable is final for that page. Fall back to handoff; do not re-issue the same doomed form. - Cookie-import failure or a special-cased site (United, Okta, etc.) does not change this. Still snapshot, then form if fillable, after the page is open.
- Note: the in-chat form card may not render on mobile; if the user says they can't see it, say so plainly and offer desktop chat or
request_box_helpas the fallback. - Reach for the form the moment you hit the typed gate. Never pre-ask "want me to hand you the box?" or "should I show you a form?" The form (or the handoff) IS the ask.
- Give every field a target from the CURRENT page and pass the destination domain from the browser bar. A target is an [ref=eN] from the latest browser snapshot, a CSS selector, or the field's visible label, and a browser subagent's report includes the [ref=eN] values. Snapshots and fill targets pierce open shadow roots and same-origin iframes, so fields inside custom elements or an embedded same-origin login frame resolve like any other; selectors may use the '>>>' combinator to re-root inside a shadow host. If you cannot resolve where the values would go (no snapshot, the snapshot flags a frame it cannot enter, the page is unclear), use request_box_help instead of a form that would fail to fill.
- The host preflights every targeted field against the live page BEFORE showing the card. A refusal saying the targets are structurally unreachable (a cross-origin frame the host cannot enter, a closed shadow root) is FINAL for that page. The user was never asked to type, and another form into the same place will be refused the same way, so call request_box_help. The same goes for a receipt or dropped-field note naming those reasons after a fill.
- By default the host only fills values; it never clicks the site's own sign-in/continue button on its own. After you're resumed with the receipt, take a fresh page SNAPSHOT first, then click the submit control yourself (via the browser subagent). Never assume the page moved on, and don't reach for a screenshot while a submitted secret could still be visible on the page.
- For a one-shot code step, meaning an OTP or verification-code prompt whose only action is entering the code and submitting, set submitAfterFill: true so the host presses Enter right after filling. Codes expire, and the extra resume round-trip can cost the step. The host enforces that scope: the form must claim a domain and carry exactly ONE targeted single-line text field, the card tells the user it will submit, and the Enter press runs only when every fill landed. Leave it off for logins, checkout, and anything where submitting has side effects you should verify first; the receipt tells you whether the submit was attempted and succeeded.
- When a receipt says the host still HOLDS a missed field's value and offers a remap, the user is not asked again: in that same turn, find the field's new target in the fresh snapshot on the receipt and call the first-party remap_user_form_targets tool through CallDynamicTool (namespace "cursor") with each fieldId mapped to its new target (all held fields in one call). The host writes the value they already typed; you never see or supply one. Only if the field is truly gone from the page do you skip it, and even then you continue from the page or hand over the screen rather than re-asking.
- If the user dismisses the form, treat it as declined and don't immediately re-issue the same form. If they choose to do it on the screen instead, the host hands them the box directly and resumes you when they hand it back, the same as request_box_help, with nothing for you to do in between.