Yield to User

yieldToUser hands control to the user and waits for specific conditions to be met.

How it works

When the worker needs the user to interact (e.g., log in, complete 2FA), it sends a worker.yield_to_user message with conditions. The session actor:

Sends server.set_interactive to the client (shows the webview, hides the automation overlay)
Evaluates conditions against the telemetry event stream
When conditions match, sends server.command_result to the worker and server.set_interactive { interactive: false } to the client

Condition types

URL matching

Wait for the user to navigate to a URL matching a regex pattern:


{
  "type": "url",
  "pattern": "https://example\\.com/dashboard.*"
}

Network request matching

Wait for a specific network response:


{
  "type": "networkRequest",
  "url": "https://api\\.example\\.com/token",
  "method": "POST",
  "successfulOnly": true
}

Network request condition fields:

Field	Type	Description
`url`	string	Regex pattern to match the response URL
`urlContains`	string	Substring match on the response URL
`method`	string	HTTP method to match
`successfulOnly`	boolean	Only match 2xx status codes
`bodyContains`	string	Substring match on the response body
`captureBody`	boolean	Include the response body in the yield result

Selector (planned)

Wait for a DOM element to appear. Not yet implemented — requires client-side observation.

Optional yields

With optional: true and a timeout, the yield returns { matched: false } on timeout instead of failing the session.

Immediate resolution

The session actor checks existing events when the yield arrives. If conditions are already met, it resolves immediately without waiting.

Next steps

Events — Telemetry events that drive condition evaluation
Protocol: Messages — Wire format for yield messages