Lease a temporary programmable phone number for receiving SMS OTP codes.

Returns the phone number (e164 format) and a session_id needed for all subsequent calls. The number is reserved for your session for ttl_seconds.

Next step: use the returned number on your target service to trigger an SMS, then call wait_for_otp with the returned session_id.

Block until an SMS OTP arrives for this session, then return the code.

Polls the AgentSIM API for up to timeout_seconds. Returns the OTP code and the message it was extracted from.

If the OTP does not arrive in time, raises a ToolError with advice on retrying. Always call release_number after you have used the OTP.

List all SMS messages received in this session without consuming the OTP.

Use this to inspect raw messages or check if an SMS arrived before calling wait_for_otp. Does NOT mark the OTP as consumed.

Release a provisioned number back to the pool.

Always call this when you are done with the session — even on error — to avoid consuming pool capacity unnecessarily.

List active sessions, optionally filtered by agent_id.

Use this to check for leaked sessions or inspect what numbers are currently active in your account.