Human Auth Delegation Overview
When a task requires real-world data or sensitive authorization, you call request_human_auth. The human on their phone approves and may return a delegation artifact — a file containing the data you need.
How It Works
- You call
request_human_auth(capability, instruction, ...).
- The human sees an authorization page on their phone.
- They approve/reject and optionally attach data (photo, audio, coordinates, code, credentials, etc.).
- You receive a result with
artifact_path and artifact_summary.
- You decide what to do next based on the artifact and current screen state.
Artifact Result Format
After request_human_auth returns, the tool result contains:
status: approved / rejected / timeoutartifact_path: local file path to the saved artifactartifact_summary: structured key-value description (kind, size, fields, etc.)
What to Do With the Artifact
Each capability has its own skill with detailed handling instructions:
| Capability |
Skill |
Typical Artifact |
| camera |
human-auth-camera |
Photo file (JPEG/PNG) |
| photos |
human-auth-photos |
Photo file(s) |
| microphone |
human-auth-microphone |
Audio file (WebM/OGG) |
| location |
human-auth-location |
JSON with lat/lon |
| oauth |
human-auth-oauth |
JSON with credentials |
| payment |
human-auth-payment |
JSON with card fields |
| sms, 2fa |
human-auth-sms-2fa |
JSON with code text |
| qr |
human-auth-qr |
JSON with scanned text |
| nfc |
human-auth-nfc |
JSON/binary NFC data |
| biometric |
human-auth-biometric |
Approval signal |
| contacts, calendar, files |
human-auth-contacts-data |
JSON/file data |
Use read(<skill_location>) to load the relevant skill for detailed instructions.
Key Principles
- You decide. The runtime only saves the artifact. You choose how to apply it.
- Redo the flow. The app's UI may have changed while waiting for human auth. After receiving the artifact, you typically need to:
- Press Back (
keyevent KEYCODE_BACK) to exit the current screen (camera preview, file picker, etc.)
- Push/prepare the data (adb push, type_text, geo fix, etc.)
- Re-navigate to the point where the data is needed (re-open picker, re-focus input field)
- Complete the action (select file, tap submit, etc.)
- Read the artifact first. For JSON artifacts (credentials, codes, coordinates), call
read(<artifact_path>) to get the actual values. OTP values are not in the session log.
- Clean up sensitive data. Delete credential/payment artifacts after use:
exec("rm <path>").
- File artifacts are auto-pushed. When you receive a file artifact (image, audio, etc.), the runtime automatically pushes it to
/sdcard/Download/ on Agent Phone and runs media scan. The result includes device_path=/sdcard/Download/openpocket-human-auth-<ts>.<ext> — this is the path you use in file pickers. You do NOT need to manually adb push.
1---2name: human-auth-delegation3description: Overview of how Human Phone authorization and delegation artifacts work. For specific capability handling, see the individual human-auth-* skills.4---56# Human Auth Delegation Overview78When a task requires real-world data or sensitive authorization, you call `request_human_auth`. The human on their phone approves and may return a **delegation artifact** — a file containing the data you need.910## How It Works11121. You call `request_human_auth(capability, instruction, ...)`.132. The human sees an authorization page on their phone.143. They approve/reject and optionally attach data (photo, audio, coordinates, code, credentials, etc.).154. You receive a result with `artifact_path` and `artifact_summary`.165. **You decide what to do next** based on the artifact and current screen state.1718## Artifact Result Format1920After `request_human_auth` returns, the tool result contains:21- `status`: approved / rejected / timeout22- `artifact_path`: local file path to the saved artifact23- `artifact_summary`: structured key-value description (kind, size, fields, etc.)2425## What to Do With the Artifact2627Each capability has its own skill with detailed handling instructions:2829| Capability | Skill | Typical Artifact |30|-----------|-------|-----------------|31| camera | human-auth-camera | Photo file (JPEG/PNG) |32| photos | human-auth-photos | Photo file(s) |33| microphone | human-auth-microphone | Audio file (WebM/OGG) |34| location | human-auth-location | JSON with lat/lon |35| oauth | human-auth-oauth | JSON with credentials |36| payment | human-auth-payment | JSON with card fields |37| sms, 2fa | human-auth-sms-2fa | JSON with code text |38| qr | human-auth-qr | JSON with scanned text |39| nfc | human-auth-nfc | JSON/binary NFC data |40| biometric | human-auth-biometric | Approval signal |41| contacts, calendar, files | human-auth-contacts-data | JSON/file data |4243Use `read(<skill_location>)` to load the relevant skill for detailed instructions.4445## Key Principles46471. **You decide.** The runtime only saves the artifact. You choose how to apply it.482. **Redo the flow.** The app's UI may have changed while waiting for human auth. After receiving the artifact, you typically need to:49 - Press Back (`keyevent KEYCODE_BACK`) to exit the current screen (camera preview, file picker, etc.)50 - Push/prepare the data (adb push, type_text, geo fix, etc.)51 - Re-navigate to the point where the data is needed (re-open picker, re-focus input field)52 - Complete the action (select file, tap submit, etc.)533. **Read the artifact first.** For JSON artifacts (credentials, codes, coordinates), call `read(<artifact_path>)` to get the actual values. OTP values are not in the session log.544. **Clean up sensitive data.** Delete credential/payment artifacts after use: `exec("rm <path>")`.555. **File artifacts are auto-pushed.** When you receive a file artifact (image, audio, etc.), the runtime automatically pushes it to `/sdcard/Download/` on Agent Phone and runs media scan. The result includes `device_path=/sdcard/Download/openpocket-human-auth-<ts>.<ext>` — this is the path you use in file pickers. You do NOT need to manually `adb push`.
pockebot